rote 


CocotTalk 1.2 Release Notes 


1. Introduction 


These notes describe Release 1.2 of the CocoTalk™ API C 
Function Library. There are several new functions added to 
CocoTalk, as well as numerous changes to the internal workings of 
several existing CocoTalk functions. However, these internal 
changes do not require any changes to any existing sourcé code. Of 


course, it is necessary to re-compile all of your old CocoTalk . 
external programs after you have installed both version 3.2 of the - 


COCO HOST and also this software. = gw: 


Section 2 denotes the procedures for both first-time installations 
and update installations. 


Section 3 contains Reference Manual pages for the new CocoTalk 
functions. REPS ae 


Copyright © 1991 Coconut Computing, Inc. All rights reserved. 
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Release Notes CocoTalk 1.2 


2. installation Procedure 


Whether you are installing Release 1.2 of CocoTalk as a new 
“customer or as an existing customer updating older software, the 
oe installation procedure is the same. 


Sign on as the UNIX super user (ie., "root’). 


2) Insert the CocoTalk diskette into the floppy drive. 


3) Ifyou are using SCO XENIX, type “install" and press RETURN; 
') if you're using SCO UNIX, type “xinstall* and press RETURN. 


4) When the installation script asks, "Next floppy?", type *y’ and 
press RETURN. 


5) The UNIX/XENIX installation script will extract the files from 
the floppy and insert them in the proper directories on your 
machine's hard disk. (The actual CocoTalk library file will be 
stored as /1{b/386/S\ ibcocotalk.a). 


6) When the install script asks you for "Next floppy?’, type “n" and 
press RETURN. 


7) If you are installing Release 1.2 of CocoTalk as an update to an 
older version of CocoTalk, you must now re-compile all of your 
external programs before users access them. 
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CocoTalk 1.2 Release Notes 


3. New CocoTalk functions 


AccessGroupsCheck() 
AccessGroupsCheckGroup() 
AccessGroupsForget() 
List ViewDisplay() 

List ViewFieldxSetQ) 
List ViewForget() 

List ViewInitQ 

List ViewltemSet( 
List ViewResponse() 
WordBitGet() 
WordBitSetQ) 
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AccessGroupsCheck 


rr LT 


~ ntax 


AccessGroupsCheck() 


5 pescinion 


" This function does two things. First, it sets the value of a global 
integer variable called myAccGrps to be the number of elements in an 
array. Then, it dynamically allocates memory for an array of 
structures that contain the names of all of the Access Groups in 
which the current user is rostered. The array is called myAccGrptst, 
and the field inside the structure that contains the group name is 
called accGroup. Thus, to access the first element of the array, you 
would refer to myAccGrplst{ 0 ).accGroup. 


Important Note 


When you are finished checking the access group information on a 

user, you should immediately call the AccessGroupsForget() 

function, so the dynamically-allocated memory is freed and the 
__RAM is usable elsewhere on the system. 


‘Return Value 


CT_OK 
FALSE 
FAIL 


See Also 


Operation successful. 
User is not rostered in any access groups. 


ieee allocating memory, or problem with access group 
les. 


AccessGroupsGroupCheck(), AccessGroupsForget() 
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AccessGroupsCheck 


ae 


; beg 
fom Int 2, ft; 
“4 CHAR ssf 80 J; 
CHAR aa{ 10 3; 
z = AccessGroupsCheck(); 
if ¢ 2 #= CT_OK ) 


then 

sprintf( ss, “You are a member of Xd access groups.", 
myAccGrps ); 

TextPlotxY¢ 10, 10, ss ); 
2 = AccessGroupsCheckGroup("abedef"); 
if ( z == CT_TRUE ) sprintf( aa, “are” ); 
else sprintf( aa, "aren't" ); ; 
sprintf( ss, "You Xs a member of access group ‘abcdef'.", aa); 
TextPlotxy¢ 10, 30, ss ); . 
AccessGroupsForget(); 2 

end ' 


endfunction 
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AccessGroupsCheckGroup 


Syntax 


"“T AccessGroupsCheckGroup( whichGroup > 
WR whichGroup( 15 3; 


Aes 
~ Description 


This function may be more useful than the AccessGroupsCheck() 
function, which returns a list of all Access Groups a user is rostered 
in. Rather, this function checks to see if a user is rostered in the 
single access group you specify with the whichGroup argument. 


Important Note 


You must have already called the AccessGroupsCheck() function 
before calling this function, After you call this function, it is 
important to free up the memory that was allocated with 
AccessGroupsCheck(), by calling the AccessGroupsForget() 
function. 


_- Return Values 


CT_FAIL AccessGroupeCheck() function was not called beforehand. 
CT_TRUE Yes, the current user is rostered {n whichGroup. | 


CT_FALSE No, the current user is not rostered in whichGroup. 


mple 


‘ See the example for AccessGroupsCheck() 


See Also 


AccessGroupsCheck(), AccessGroupsForget() 
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AccessGroupsForget 


Syntax 


INT AccessGroupsForget() 


Description 

This function frees the memory that was dynamically allocated with 
the previous call to AccessGroupsCheck(). Thus, this function 
should ONLY be called if you have previously called the 
AccessGroupsCheck() function. 

Return Values 


CT_FAIL Memory was not already allocated. 


cT_OK Operation successful . 

Example 

See the example for AccessGroupsCheck() 
See Aliso 


AccessGroupsCheck(), AccessGroupsCheckGroupQ) 
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tax 


wn. ListViewWisplay( r 3 
RECT Fr; 


~ Yescription 


This function sends the previously-initialized ListView to the 
COCONET Access Program (CAP), displaying it within the window 
defined by the r argument. In order for the user to be able to 
interact with the newly-arrived ListView, you must call the 
List ViewResponse() function after you call this function. 


Return Values 
CT_OK Operation successful. Now call ListViewesponset) 
CT_BADCAP User's using an old CAP. Must be version 


91.09 and higher. 


CT_CAPALREADYHASIT CAP already has this ListView, which means the 
CAP already has a ListView in memory whose ID 
code matches the ID code of the ListView you 
just initialized with ListViewInit() prior to 
calling ListViewWisplay(). When ListVieDicplay(> 
returns this value, it does not mean an error 
has occurred. Rather, it simply means the CAP 
already has & ListView with this ID. 
Typically, this {s a good thing, because the 
CAP does not have to spend time receiving all - 
of the ListView's data. If the contents of 
the list have changed since the last time the 
List was sent to the CAP, then you should fist 

' call ListViewForget() before calling the 
ListViewInit() and ListView isplay() 
functions. That way, the CAP will not have an 
old copy of the ListView in memory. 


CT_FAIL : There was an internal error. 
Example 
See the example in List ViewInit(). 

~ See Also 


List ViewInit(), List ViewForgetQ 
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List ViewFieldxSet 


Syntax 


INT ListViewFieldxSet( fieldNumber, pixelsFromleftBorder ); 
WORD fieldNumber; 
WORD pixelsFromleftBorder; 


Description 


This function is used to set the relative x coordinate for each field 
in the ListView window. The pixelsFromLeftBorder argument 


specifies how far to move to the right (in pixels) to position the 
column for a particular field. It is recommended that the first field 
(field 0) be set to 5 pixels in from the left border. : 
Return Value 

CT_OK Operation successful. 

Example 

See example in List ViewInit(). 

See Also 


List ViewInit(). 
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ListViewForget 


Syntax 


T ListViewForget( idCode ); 
RD idCode; 


ie Description 
Tells the CAP to "forget" (ic. free up dynamically-allocated 
memory) a ListView whose id code is specified in the idcode 
argument. If the CAP has already “forgotten” or does not have this 
ListView in memory, the request is ignored. 
Example 
See the example in List Viewinit(). 
See Also 


List Viewlnit() 


- 


ListViewlnit 


Syntax 


ListViewInit( td, ti, vi, ff, de, ub, uf, sb, sf, fh, fn, fs, f >; 
WORD id, ti, vi, fis 

CHAR de; 

WORD ub, uf, sb, sf, ih, fn, fs, f; 


Description 


List ViewlInit() is used to initialize a ListView. ListViews are 


scrollable lists of items that appear on a CAP user’s screen. The ~ 


ListViewlnit() function initializes various parameters so that your 
external program sends the correct information to the CAP when 
you subsequently call a ListViewDisplay() function. What 
List ViewInit() does behind the scenes, among other things, is set 
the fields of the temp _lv structure. Typically you will not need to 
access or refer to the temp lv structure directly. (The ‘temp Iv 
structure is to List Views as the temp_popup structure is to PopUp 
menus.) 


What follows is a more detailed description of each argument to the 
ListViewInitQ function: 


Arg Meaning 

id Identification code 
This is the ListView’s id code. It is a number, designated by 
you, in the range 10000 to 64000. 


ti Total items 
This is the total number of items that will be shown in the 
List View. 


vi _—_ Items per view 
* This is the number of items that appear inside a ListView’s 
window. Most likely this number will be between 5 and 20. 


fi Number of fields per item 
This is the number of separate “fields” that each item 
contains, The ‘minimum number of fields is 1, and the 
maximum is 12. 
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ListViewInit 


ub 


Le 


Delimiter char 

This is the delimiter character that will be used to separate 
the item fields when your program sends the ListView items 
to the CAP. There are five possible delimiters to choose 
from: the TAB character (hex 09), and the following four 
characters: ~, *, |, or #. Use the delimiters which is 
guaranteed not to appear as data within a field within an 
item. Typically, the best delimiter to use is the TAB. The 
example code below uses the TAB delimiter. 


Unselected item background color 

This is the color of the background of the ListView window. 
The valid color values are the same as those for the Color() 
function. 


Unselected item foreground color 

This is the color of the unselected items in the ListView 
window. There is only one selected item at any given time. 
All other items in the List View window are “unselected", and 
will be plotted with this foreground color. The valid color 
values are the same as those for the Color() function. 


Selected item background color 

This is the color of the “selection bar" behind which the text 
of the selected item appears. The valid color values are the 
same as those for the Color() function. 


Selected item foreground color 
This is the foreground text color for the selected item in the 
ListView window. The valid color values are the same as 
those for the Color( function. 


Item height 

This is the height, in pixels, of each item in the list. If you 
are using the DefaultFont (which we recommend) for your 
ListView, then the value of ih should be 11. 


Item font number 

The text of the ListView items will be plotted in the font 
indicated by this font number. The valid font number values 
are the same as the SetTextStyle() function. 
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Eaviovantt 


fs  ItemFontSize 


ips 


The text of the List View tems will és plotted in the fot sis 
indicated by this number Valid sizes are 1 through 10, for 
this release. However, it is recommended that you only use 
size 1 and set the fn argument to DefaultFont. 


f Flags 


These are various flag bits that can be set to ON or OFF 
The following table lists the constant names of the flags, as 
well as their meanings: 


CF 


Note that if the bit value is 0 for a given bit, then that feature is 


considered "disabled" 


Bit Flag Heme 
O LVF_ENABLED 
1 LVF_FKEYS_OK 


2 LVF_ALTKEYS_ OK 


3 LVF_AZO9KEYS_OK 
4 LVF_CURSKEYS OK 


5 LVF_TABKEY_OK 


8 LVF_SCROLLBAR_OK 
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Description 
Should be set to 1 for this release. 


If 1, the function keys Fi-F10 can be 
pressed while the user {8< in this; 
Listview. It {8 up to you td determine 
what to do next AE Sane eee pera 


If 1, the ALT keys from ALT-A to ALT-2 are ™: 


available while user fs In this ListView. 
It 1s up to you to determine what to do 
next if a user has pressed an ALT key. 
ALT keys are often used {f Button()s are 
on the screen. 


Reserved for future use. Leave set to 0 
for this release. 


Reserved for future use. Leave set to 0 
for this release. 


If 1, the TAB key is enabled while the 
user {8 using this ListView. It fs up to 
you to determine what to do next if the 
user presses TAB. 


Reserved for future use. Leave set to 0 
for this release. 


Reserved for future use. Leave set to 0 
for this retease. 


If 1, the scroti buttons are enabled on 
the 
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List Viewinit 


9 LVF_OLDLIST_OK 
0 LVF_MOUSEINVIEW_OK 


e. y LVF_MOLSEXUTSIDEVIEW OK 


12 LVF_PARTIAL_OK 


3 ° 
4 ° 


15. LVF_ADDITEM_OK 


~ Yeturn Values ° | 


Reserved for future use. Leave set to 0 
for this retease. 


If 1, then if the user has a mouse, the 
user can select an item with the mouse. 


If 1, then if the user has a mouse, the 
mouse is enabled anywhere on screen, even 
outside of the ListView window. This is 
useful {if you have buttons or icons 
elsewhere on the screen that you want to 
be able to access. 


If 1, then when you run ListViewWisplay(), 
the list will be sent in “chunks", where 
the size of the chunk is equal to the vi 
argument shown above. 


Reserved for future use. Leave set to 0 
for this release. 


Reserved for future use. Leave set to 0 
for this release. 


Reserved for future use. Leave set to 0 
for this release. 


CT_OK. i The ListView was initialized successfully. 


CT_BADARG~ ‘Invalid value for one of the arguments. 


CT FAIL ,., Was not able to initialize the ListView. 
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ListViewlnit 


Example 


define MY_LV_DELIM 
fidefine MY_LV_IDCODE 


RECT r, SetRect(); 


LVRES Ivrez: /* the 


0x09 
10001 


result structure for ListViewResponse() */ 


static char *days(7} = 


{ “Sunday”, 


"Thursday", 

“Friday”, 

“Saturday” 
3 


/* first, let's set the flags for this ListView */ 
/* first set all the bits to zero */ 


f = (WORD)O; 


/* now set scrollber bit to on, and the mouse-in-view bit to 
on so user will be able to use mouse to click on items */ 

f = WordBitSet( f, LVF_SCROLLBAR_OK, 1 ); 

f = WordBitSet( f, LVF_MOUSEINVIEW_OK, 1 ); 


J/* Wow initialize this ListView */ 


2s ListViewinit¢ 


3 


MY_LV_IDCODE, /* idCode */ 

7, /* totalitems */ 

3, /* itemsPerView */ 
3, /* fieldsPeritem */ 
MY_LV_DELIN, 7/* delimchar */ 
LIGHTGRAY, /* unselBGC */ 
BLACK, /* unselFGC */ 
BLACK, /* selBGC */ 

WHITE, /* selFGC */ 

11, /* itemHetght */ 
DefaultFont, /* {temFontNumber */ 
1, J/* itemFontSize */ 
f /* flags */ 


/* if ListViewInit failed, let's get outa here */ 
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ListViewInit 


if ( z I= CT_O«K ) 
then 
sprintf( ss, “LVInit Failed. Error = %d. Press ESC.", z ); 
TextPlotxy( 0, 0, ss ); 
z ® WaftForESC(); 
2 return; /* just for example purposes... 
2 a) exiting this function */ 


/* if you got this far, then ListViewInit() succeeded... */ 


/* There are two fields in this example ListView. 
The first field will Just be a number, 1 thru 7. 
Let's make it appear at 5 pixels to the right of the left 
side of the ListView's window. The second field is the 
day of the week; let's make it appear 40 pixels in. */ 


ListViewFieldxSet( 0, 5 ); /* item 0 is the ist item */ 
ListViewFieldxSet( 1, 40 );  /* item 4 is the 2nd item! */ 


/* now initialize the fields of this LV's items */ 

/* set i to zero, but remember to display i's value as 1 plus ji, 
so it looks like 1 thru 7, not 0 thru 6, which it actually is, 
behind the scenes! */ 


oop 
/* each item, in this example, will be like thiss 
<number><del iaiter><string> 
where the number is just the number 1 thru 7, 
and the string is the day of the week */ 


sprintf( ss, “XdXcX%s", +1, MY_LV DELIM, day {J ); 
z = ListViewltemSet( fit+, ss ); 


endl oop 
vile( +41 < 7); 


_" ok, now draw a window on the screen */ 
r = SetRect( 40, 110, 300, 150 ); 
ActionWindow3D( r, DARKGRAY, BLACK, BLUE, “Select a Day" ); 


/* now display the listview to the user */ 

/* note that the coordinates for this ListView's window are 
set so they'tl fit snugly within the Actiondindow that we 
just drew before */ 

z= ListViewWisplay( SetRect( r.LXx+2, r.L¥+22, r.RX-2, r.RY-2 )); 


/* 
If all went well, CAP will return CT_OK or CT_CAPALREADYHASIT, 
the former meaning that it was displayed to the user, the latter 
-) meaning the CAP already had this ListView's 1D so it just 
aplotted what ft already had. 
/ 
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ListViewinit 


/* It's important to check {f something went wrong, however ai “ 


if ¢ ¢ 2 f= CT_OK ) AND ( 2 f= CT_I CAPALREADYHASIT i a 
then 
sprintf¢ a, _mbVDisplay Failed. Error = Xd. read esc.", 


TextPlotxy( % 0, s8 ); 
22 Wal tForESC(); 
return; /* just for exemple; exiting this function */ 


/* Ok, tell the CAP to go shead and let user select an tte. 
from the ListView. Note the second argurent 1¢ prece 
an ampersand (&) character, since you'ré dealing with™ 
a pointer to the lzrez struct. */ ee re 

2 = ListViewResponse( MY_LV. POON: Blvrez p00 ‘ae , 


if ( 2 == CT_SHIFTESCPRESSED ) 

then we 
ListViewForget( MY_LV_IDCODE ); it eras Mea 
return; /* just an example... ; 
you'd prolly do something else */ 


{ = lvrez.{itemSelected; 
if ( z == CT_OK ) /* CAP says everything tent strtot v 
then es 
sprintf( ss, “You selected item number Xd!", 
(vrez.ftemSelected ); 
/* print some feedback on the screen, under the window 7 


Color( YELLOW ): ” 
TextPlotxY( r.LX, r.RY+10, ss >: 


endfunct fon ; ‘ 
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List ViewitemSet 


Syntax 


 ListViewstemSet( {temNumber, itemString ); 
10 iteaNumber; 
\R itemString£ 128 1; 


~~ Description 


This function is used to set the text of each item in a ListView. 
Typically this function will be called inside a loop, so that you can 
set each item from item 0 (the first item) to item n (where n is 1 
less than the total number of items in the List View that you already 
initialized with ListViewInitQ). This function dynamically allocates 
memory for the string you specify (the memory is freed with the 
next call to List ViewInit(Q) or when the CocoTalkFinish() function 
is called just before your user exits your external program. 


important Note 


The itemstring argument in this function refers to the string that 
contains the text of the ListView item’s fields, along with delimiter 
7 characters placed between the fields. To build a ListView item’s 
>.) string, it is best to use the sprintf() C function. Consider the string 
below, with 4 fields, the first being a number, the second being a 
string, the third being a number, and the fourth being another 
te | 
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List ViewResponse 


Syntax 


ListViewResponse( idCode, ivResp ) 
» idCode; 
LvxES *\lvResp; 


a “Description 


This function tells the CAP to allow the user to select an item in 
the ListView previously sent with List ViewDisplay(). 


If List ViewResponse() operates successfully, it will set the 

ivResp structure to contain detailed information about which item 
the user selected, and how the user selected the item (i.c., either by 
keyboard or mouse). The tvesp structure is defined as such: 


typedef struct (v_result_structure 


begin 
WORD type_of_response; Vs will have a LVR_xxx value */ 
WORD mG * mouse x */ 
WORD my i mouse y */ 
WORD «Le /* which Le button was pressed */ 


WORD itemSelected; /* which ListView item was selected */ 
BYTE key1Pressed; /* key pressed (ASCII 32-126) or 0 */ 
BYTE key2Pressed; /* meaningful only if keyiPressed==0 */ 


LVRES; 


The possible values of the type_of_response ficld within the Lvres 
structure are as follows: 


ve Name Meaning 
LVR_NONE Should not ever get this value. 

1 LVR_ESC User pressed ESC key. 

2 LVR_SHIFTESC User pressed SHIFT-ESC. 

3 LVR_ALTKEY User pressed an ALT key. 

4 LVR_FKEY User pressed a Function key. 

5 LVR_RETURNKEY User pressed RETURN. 

6 LVR_TABKEY User pressed TAB. 

7 LVR_MLEFTINVIEW L mouse button in ListView. 

8 LVR_MRIGHTINVIEW R mouse button in ListView. 

9 LVR_MCENTERINVIEW mouse button in ListView. 

10 LVR_MLEFTOUTVIEW L mouse button outside ListView. 
fe 8 LVR_MRIGHTOUTVIEW § & mouse button outside ListView. 
_° f LVR_MCENTEROUTVIEW M mouse button outside ListView. 
a 13 LVR_SENOMORE Reserved for internal use. 
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List ViewltemSet 


The code to set this item string might look like this: 


CHAR ss{ 90 ); 
CHAR de = 0x09; /* TAB delimiter */ 
INT 23 
/* 
Notice that delimiters should only be placed 
BETWEEN fields, but not BEFORE the first or 
AFTER the last field 
*/ 


sprintf( ss, "XdX%cXsxcXdXcXs", 
12345, de, "fred", de, 101, de, “smith” ); 


z = ListViewltemSet( 0, ss ); 


« « « /* continue with more code to set other items */ 
Return Values 


CT_OK Operation Successful 

CT_BADARG Invalid item number. Valid range is 0 to n, where 
n ts the total number of items (minus one) that was 
already specified in a previous call to 
ListViewInit(). 


CT_BADARG also may mean that the length of the string exceeded 
the maximum limit. 


CT_NOTALLOC Was not able to allocate memory for this string. 
Example 
See the example for List ViewInit(). 


See Also 


List ViewForget(), List ViewFieldxSet(), List ViewlnitQ) 
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List ViewResponse 


Return Value * 

CT_FAIL Internal error, or CAP error. 

CT_ESCPRESSED User pressed ESC. 

CT_SHIFTESCPRESSED User pressed SHIFT-ESC: this means you should 
immediately close all files, free any 
dynamically-allocated memory, call 
CocofalkFinish(), and exit your external 
progrem, as the user has {ndicated he or she 
wishes to return to the Main Menu. 

CT_OK Operation successful; check the values in the - 
LVRES structure for detafled info. 

Example 

See example for List ViewInitQ . 

thea) 

See Also ; 

Sy bt hag eg: 

List Viewlnit(), List ViewDisplayQ) Wea 
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WordBitGet 


Syntax 


WordBitGet( target, whichBit ) 
) target; 
-- ane whichBit; 

t 


Description 


WordBitGet returns the current value of the specified bit in the 
specified WORD variable. 


Return Value 


0 The specified bit is set to 0. 
1 The specified bit {is set to 1. 
Example . 


exampte() 
begin 
WORD Wj 
2) ws 12345; 
ee sprintf es, “w= hd, the fifth bit is set to %d.", 
w, WordBitGet( w, 5 ) 3 
of TextPlotxy( 0, 0, ss ); 
" . endfunct ion 
Also 


WordBitGet() 
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WordBitSet 


Syntax 


WORD WordBitSet( target, whichBit, onoff ) 
WORD target; 
INT whichBit; 


Description 


WordBitSet sets the specified bit of the specified target WORD 
variable to the specified value, either 0 or 1. 


Return Value 


WordBitSet returns the new value of the WORD variable, with the 
specified bit now set. 


Example 


% ‘ /* first, let's set the WORD variable to zero */ 
eet w2 0; 


/* let's now set the fifth bit to be ON */ 
ws WordBitSet( w, 5, 1); 


/* let's print out the value on the screen now */ 
sprintf( ss, "Now the vatue of w is X%hd.”, w ); 
TextPlotxy¢ 0, 0, ss ); 


endfunct fon 


See Also 


WordBitGetQ 
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Reference Manual 


CocoTalk" 


Reference Manual 


CocoTalk™ 


Applications Program Interface Library - 


Copyright © 1990 Coconut Computing, Inc, All rights reserved. 


First printing, August 1990. 
Second printing, February 1991. 


The software described in this manual is subject to the conditions 
‘nd rules set forth in the License Agreement. You may make-as ™ 
"gnany copies of the software as necessary for backup purposes only. . 

No part of this guide may be reproduced or transmitted in any form 

or by any means, electronic or mechanical, including photocopying 

and recording, for any purpose other than the purchaser’s personal 

use without written permission from Coconut Computing, Inc. 


onut Computing, Inc. makes no express or implied warranties 

| regard to this documentation and software, including 
merchantability or fitness for any purpose. Coconut Computing, 
Inc, shall not be liable or responsible for damages of any kind, 
including special, indirect, or consequential damages, arising out of 
or resulting from any program, services, or materials made available 
hereunder or the use or modification thereof. 


COCONET is a registered trademark and service mark and 
CocoTalk, CocoTunes, CocoBrowse, CocoFace, CocoMail, ~, 
ee JserBase and Coconut are trademarks of Coconut Computing, Inc. 


SCO is a registered trademark of Santa Cruz Operation. 
UNIX is a registered trademark of AT&T. 

XENIX is a registered trademark of Microsoft Corporation. 
PC Paintbrush is a registered trademark of Zsoft Corporation. 


CocoTalk I.l Release Notes 


CocoTalk™ (Version 1.1) 
Changes and Enhancements 


"endif" removed 

The “endif” substitute for the close brace ("}") has been removed. 
Use "end" instead. If you do not use “begin”, “end”, “then”, etc., 
then you can ignore this change. 


PolyPointSet(n,x,y) 
Used to set one pair of xy coordinates in the PolyPoints[] array. 


VT100 Text Mode commands added 

Several functions have been added to support VT100 terminal 
capabilities for “textonly’ users. These functions only work if 
“textonly = = TRUE": 


TextPlotcL¢ c, l, txt ) Display a text string ot at column c, 
ine |, 

TextHodeBold() Turn on bold text attribute 

TextModeReverse() Turn on reverse text attribute 

TextHodeNormal () Reset text attribute to normal 

TextHodeBlink() Turn on text blink attribute 

TextNodeUnderscore() Turn on underscore text attribute 


These functions are designed ONLY for VT100 emulation. For 
fuller support of ASCII terminal emulation, use the UNIX ’curses’ 
library. Note: These routines will return CT_NOTTEXTONLY if 
run by a CAP user. 


BitmapSend() Enhancements 

The BitmapSend() function had been enhanced so that it can send 
ZIPPED PCX files. A ZiIPped file is one that has been 
compressed using the zip/unzip utilities available from most bulletin 
boards and online services. You can now zip the .PCX file image, 
and the COCONET Access Program will automatically unzip the 
file before displaying it. One file per zip. For many PCX images, 
the ZIP file size will be one tenth or one eighth the size of the 
unzipped .PCX file. 
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Introduction 


The CocoTalk Applications Program Interface (API) is a collection 
of C language functions for writing “external programs" for your 
COCONET HOST system running under the SCO XENIX 386 
System V or SCO UNIX 386 System V operating system. 


"External programs" in the COCONET meaning of the phrase are 
application programs, written in C with the CocoTalk library, that 
are “called” by the COCONET HOST program. Typically, external 
programs are called when users select items from the Features 
menu of the main menubar of your COCONET system. 


The optional "WELCOME", "NEWUSER‘, "ABOUT", and 
"GOODBYE" external programs that you can add to your HOST 
system are also CocoTalk C external programs. 


In order to make use of the CocoTalk API Library, it is assumed 
that you have a working knowledge of and experience using the C 
programming language. 


CocoTalk enables you to create your own custom C-language 
applications for your online service’s users. Applications include: 
front ends to database programs, order processing programs, online 
graphical games, text file viewers, etc. The CocoTalk API Library 
contains a wide variety of functions for manipulating the user’s 
display as well as receiving input from the user. 


The vast majority of CocoTalk functions are designed with the 
assumption that the end-user will be connected to your system via 
a COCONET Access Program (CAP). Thus, you'll find a heavy 
emphasis on graphics routines for the CAP. Most CocoTalk 
functions work directly with the CAP by “talking” to it and 
“listening” to it. Hence, the name “CocoTalk"! 


If a user of your online service is connected via a simple ASCII 
terminal connection, or is dialed up via modem using a 
telecommunications program running in ASCII mode, a variable 
called textonty will be set to TRUE. When textonly is TRUE 
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phics are not displayed. Be sure to check the Reference section 
‘his manual to see how a particular CocoTalk function behaves 
wuael textonly is TRUE. 


When users are accessing your system via a CAP, the value of 
textonly will be set to FALSE. 


464 CocoTalk API Library 


The CocoTalk API Library requires the following software: 


® One of the following operating systems 
- SCO XENIX 386 System V (version 2.2.3 or higher) 
- SCO UNIX 386 System V (version 3.2.0 or higher) 


© The corresponding SCO Developer’s Kit for the operating 
system (which contains the C compiler you'll need to compile 
your external programs) 


© A license for a COCONET HOST package. The CocoTalk 
Library will not work without the HOST software. 


1.2. Filling out and retuming the Customer Registration Form 


ae Before you begin, please take a minute or two to fill out the 
ra Customer Registration Form that came with this software package. 


Only by filling out and returning the Customer Registration Form 
can you benefit from Coconut’s technical support, future updates, 
new product announcements, receipt of occasional newsletters, and 
other benefits that may be made available from time to time. 


1.3. Installing the CocoTalk API Library 

Installation is easy, and should not take more than 5 minutes. You 

will need to install the software using the UNIX "root", or super- 

user, login ID. 

Step 1. When you're ready to begin, sign on to your UNIX 
machine as the "root", and insert the CocoTalk diskette in 
your machine’s floppy drive. . 

Step 2. The entire CocoTalk library is contained on a single 
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floppy diskette. You'll be using the "install" command to 
copy the contents of the floppy onto your hard disk. 


If you are using a 5.25" 1.2MB “a:* drive (floppy drive 0), 
and you're running SCO XENIKX, type: 


install /dev/r fd096ds15 


If you are using a 3.5" 1.44MB or 720K *a:" drive (floppy 
drive 0), and you’re running'‘SCO XENIX, type: 


instal l/dev/rfd0135ds9 


If you are using a 5.25" 1.2MB “b:* drive (floppy drive 1), 
and you’re running SCO XENIX, type: 


install /dev/rfdi96ds15 


If you are using a 3.5" 1.44MB or 720K "b:" drive (floppy 
drive 1), and you’re running SCO XENIX, type: 


install /dev/rfd1135ds9 


NOTE: If you're running SCO UNIX, use “xinstall"’ 
instead of "install", 


When the “install” program is complete, you’re done! The 
CocoTalk linkable library will be placed in the /lib/386 
directory, and the four CocoTalk include files will be 
placed in the /usr/include directory. 


A set of example programs is also included on the 
CocoTalk diskette. These example C programs are 
copied to the /tmp directory. You'll need to copy the 
example source code to the appropriate subdirectory on 
your system. 


At this point you can remove the CocoTalk floppy 
diskette from the floppy drive. Keep the diskette in a safe 
place! You're now ready to begin using CocoTalk. 
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1.4. An important warning 
The CocoTalk files should not be edited! 


WARNING: Do not make any modifications to the cocodefs.h, 
cocostru.h, cocoglob.h, cocoincl.h, or cocotalk files.’ They are all 
used by the cocotalk linkable library file and if modified may cause 
loss of data or malfunctioning programs. In order for CocoTalk to 
work, these files must not be edited. ee et 


1.5. Some common reserved words - 


You may notice words like "begin", "then", end’, and “endfunction" 
in the code examples within this manual. These words are 
CocoTalk C preprocessor definitions that have the following 
equivalents in C: 


CocoTalk Cc CocoTalk Cc ial 


begin r INT tne 
then € WORD } unsigned short int 
end d CHAR char 
endfunct fon ) BYTE unsigned char 
loop € LONG long int 
endloop ) AND rT} 

OR {If 

Wop x 


The CocoTalk words are substitutes for the C language symbols 
and are used throughout this manual (as well as throughout the 
CocoTalk source code) to make the job of reading the code less 
difficult by reducing ambiguity and increasing clarity. When you 
write C programs with CocoTalk, you have the choice of using the 
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CocoTalk substitutes or the C symbols; use whatever you’re more 
ifortable with. See Appendix C for an explanation of all of the 
srved words in CocoTalk. (> 


Par 


1.6. Some important notes 


@ Matching HOST and CocoTalk versions 

Your CocoTalk library version must match the version of the 
COCONET HOST software you're using, That is, if you're 
using a 4-user HOST program, you'll need the 4-user version 
of the CocoTalk library. If you upgrade your COCONET 
HOST software, you'll need to contact Coconut Computing 
for an upgrade to the CocoTalk library. It is important that 
the COCONET HOST and CocoTalk software match, 
otherwise the HOST program and your external programs 
may work unpredictably, may crash, or cause loss of data. 


@ Checking the value of textonly 


the valuc of textonly. If set to FALSE, the user is using a 
CAP. Otherwise, no. The textonty variable and other 
CocoTalk variables are set when you call the CocoTalkStart() 
function, which you must do at the beginning of your 
program. 


Example; 
exanple() 
Begin 7 


if ( textonly == TRUE ) 
then 
we connected in ASCII mode.\n"); 


else 
begin 
Color( WHITE ); 
TextPlotx¥( 50, 50, "You're in graphics mode."); : 
) end 2 
endfunct fon 
“1-8 CocoTalk API Library 
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@ Checking for screen resolution 
If the user is connected online using a COCONET Access 
Program, you can check for the screen resolution of the 
machine the user is using by checking the value of GetMaxX 
for the horizontal resolution, and GetMaxY for the vertical. 


You can also check the values of GraphDriver and 
GraphMode to determine what kind of graphics the user is 


using. 
Here are the possible values for GraphDriver and 


GraphMode, along with their corresponding X and Y 
resolutions: 


GraphDriver GraphMode colors GetMaxX GetMaxY 


VGAmode VGAmed 16 639 349 
VGAmode VGAHE 16 639 479 
EGAmode EGAHI 16 639 9 
HerciHono HercHonol{ 2 719 7 


1.7. Include files 


The following four lines of code must be added, in the order shown, 
to the beginning of your CocoTalk programs: 


#include <cocodefs.h> 
#include <cocostru.h> 
#include <cocoglob.h> 
#include <cocofnel.h> 


These files contain definitions, constants, data structures, and 
variables that CocoTalk uses internally, Nothing in these files 
should be edited and the source code inside the files should not be 
modified in any way. Any modifications may result in loss of data 
or program crashes. 


CocoTalk API Library 1-9 


i aaa tos ba ae ees Sai er aia a aia ae li a te I ee Lc et ee ei ae et 


Introduction 


Remember, in addition to adding the four #include lines at the top 
beginning of each CocoTalk program you write, you'll need to 
both a CocoTalkStart() function call to the beginning and a 
-. «v0TalkFinish() function call to the end of your main() function 
‘. lode. If the CocoTalkStart() function is not called, none of the 
CocoTalk functions will work (i.c., they will return a value of 
CT_BADCOCOTALK). See the pages for CocoTalkStartQ) and 
CocoTalkFinish() in the reference section of this manual. 


1.8. Compiling your program 


To compile your external programs under SCO XENIX, type the 
following at the command line: 


ce -O abc.c -o ABC -lcocotalk -Ix 


where abc.c is the name of your external program. The °-k” 
command line parameter must be present in order for your 
a sbi ha to compile. The CocoTalk routines make use of some of 
~ \e functions available only via the "-Ix" parameter. 


If you’re using SCO UNIX, you'll need to compile using a different 

set of arguments. CocoTalk programs compiled in SCO UNIX will 

~-- 1 to be compiled with the -XENIX argument, so that the output 
s in the OMF executable file format. A typical command lin 
it look like this: : 


ce -O abc.c -lx -o ABC -xenix -link cocotalk 
or, alternatively, 


ce -O abc.c -lx -o ABC -xenix -tink /tib/386/Slibcocotalk.a 
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2.1 Tech Support Phone Numbers 


Coconut Computing, Inc. wants to provide you with the best 
possible support so that you can get the most out of your purchase, 
and create the best possible applications for your online service. 


For your convenience, we’ve set up several means for getting 
technical support. Consult the list below whenever you need to give 
us a call, send us a fax, or dial up to our in-house Tech Support 
system. 


To help us handle your questions as quickly as possible, please have 
the following information available when calling: product name, 
version number, serial number, and your computer name, model, 


and operating system. 


Voice Line: 619-456-5052 
Hours: Yarn-Spm, Pacific Time 


. FAX: 619-456-1905 
; Hours: 24 hours, 7 days a week 


COCONET Tech Support 619-456-0815, 1200/2400bpe, 7-E-1 
BBS: Hours: 24 hours, 7 days a week 


CompuServe e-mail: 70034,1062 
Hours: 24 hours, 7 days a week 


internet e-mail: | support@coconut.com 
Hours: 24 hours, 7 days a week 
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ActionWindow 


Syntax 
INT Actionilindow( r, wine, borde, he, htxt ); 


RECT re; 

WORD wine; 

WORD borde; 

WORD he; 

CHAR htxt[ maxten_title }; 


Description 


This function instructs the CAP to draw a rectangular area 
(specified by r) with a window color of winc, a border color of 
bordc, a header color of hc, and a text message in hit. The text 
will automatically be centered within the r.LX and r.RX¥ 
boundaries. 


The header text’s color is always wHITe, displayed within a black 
background. The header text should be 49 characters or less in 


i: length. 
eer 
+) 
Return Values 
CT_OK Successful operation. 
CT_BADCOLOR Not a valid color value. 
CT_TEXTTOOLONG Header text too long. 
Textonly 


Sends "[[ " followed by the Aat string followed by * }]\n". 
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ActionWindow 


Example 


naa 


in 
' RECT b, SetRect(); 


INT 2; 
b = SetRect( 100, 140, GetMaxX-100, 220 ); 


/* displays an ActionWindow in center of screen */ 
z = Actiorivindow{ b, DARKGRAY, BLACK, BLUE, “Hello, world!" ): 
endfunct ion 


See Also 


ActionWindow3D(Q), ActionWindowClear(), 
ActionWindowBottomMessage(), FilledBox() 
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ActionWindow3D 


Syntax ‘ 
INT ActfonWindow30( r, wine, borde, he, htxt ): 


/ ay RECT r; 
; WORD wine; 
WORD borde; 
WORD he; 
CHAR htxtl maxlen_title ); 


Description 


Same as ActionWindow(), except it gives a 3-dimensional feel to 
the image by adding shaded edges to the rectangular areas. 
Because of this, the coordinates of the r argument must all be at 
least 2 pixels in from the screen boundaries. 


Return Values 


" CT_OK Successful operation. 
CT_BADCOLOR Not a valid color value. 
CT_TEXTTOOLONG Header text too long. 
CT_BADARG One or more coordinates too close to 
screen edge. DO 
Textonly 


Sends *[[ " followed by the htxt string followed by * J]\a". 


See Also 


. ActionWindow(), ActionWindowClear(), 
i, ActionWindowBottomMessage(), FilledBox() 
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ActionWindowBottomMessage 


Svntax 


' ActfonlindowottomMessage( r, winc, messc, messtxt ) 
“RECT r3 
WORD winc; 


WORD messc; 
CHAR messtxt[ mexten_title J; 


Description 
Tells the CAP to plot a “bottom header" bar and centered text 
message in the SmallFont. Assumes that a previous call to 
ActionWindow() has been made. 
Return Values 
cTLOxK Successful operation, 
“SFr sancovon Not a valid color value. 


CT_TEXTTOOLONG Too many characters in messi. 


Textonly 
ds the messtet string followed by a *\n’. 


Example 

exemple() 
a a 
RECT b, SetRect(); 
b = SetRect( 100, 100, GetMaxx-100, 250 ); 
Actfonilindow( b, DARKGRAY, BLACK, BLUE, "Hello, world!® ); 
ActioritindowBottomMessage( b, BLUE, WHITE, 

- “Press ESC to exit"); 


endfunction 
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ActionWindowBottomMessage 


See Also 


ActionWindow(), ActionWindowClear(); 
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Ou-mtgy 
ActionWindowClear( rect, window, borderC ) 


RECT rect; 
WORD window; 
WORD borderC; 


Description 


Tells the CAP to erase the contents inside an ActionWindow 
whose coordinates are specified in rect. It simply replaces the 
body of the ActionWindow with a filled rectangle, the fill color 
being windowC, and the border color being borderC. If you do 
not wish to have a fill color, use No_Filt as the value of windowC. 
Likewise, you can specify no border by setting borderC to 
No_Border. 


-Return Values 
) 
CT_OK Successful operation. 
ct_sapco.on § Value of windowC and/or borderC is out of 
' fange. 
\lso 


ActionWindow(), ActionWindowBottomMessage(), FilledBox(); 
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Syntax 
INT Arc( x, y, startangle, endangle, xradius, yradius } 
WORD x; 
WORD y; 
WORD startangle; 
WORD endangle; 


WORD xradius; 
WORD yradius: 


Description 
Tells the CAP to draw an arc whose center is x, y, from startangle 


to endangle, with radii of xradius and yradius. Valid values for 
startangle and endangle are 0 to 360. 


Note : gees 
The angle values for Arc() are determined in a counterclockwise 
fashion, starting with 0 degrees at 3 o'clock, 90 degrees at 12 
o'clock, 180 degrees at 9 o'clock, and 270 degrees at 6 o'clock. 

Return Values 
CT_OK Successful operation 


CT_BADANGLE Invalid value for startangle or endangle. 
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Arc 
Example 
xample() a 
egin ‘a 
INT 2; aoe 
/* draws a yellow smile face */ 
Color( YELLOW ); 
z= Circle( 320, 175, 50 ); 
z= Circte( 310, 160, 5 ); 
z = Circle( 330, 160, 5 ); 
z = Arc( 320, 175, 200, 340, 40 ); 
endfunct fon 
Textonly 
_-~, Function ignored in textonty mode; returns CT_oK > 
) Ces 3 
See also 
Ellipse(); 
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Bar 


INT Bar( x1, yl, x2, y2 ): 
WORD x13 
WORD yt; 
WORD x2; 
WORD y2; 


Description 
Tells the CAP to draw a bar on the screen with the given 
coordinates. The bar’s color and pattern must be set with a 
previous call to SetFillStyleQ. Bar() is useful for drawing bar 
graphs for displaying statistical or numeric information in a 


— | ? 
| 
| 
graphical format. 

| 


Return Value 


: ~) Always returns CT_oK. 


Textonly 


Function is ignored when in textonly mode. 


See also 


SetFillStyleQ, Bar3D(; 
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Description 


Tells the CAP to draw a three-dimensional bar on the screen with 
the given coordinates. The bar’s color and pattern can be set with 
a previous call to SetFillStyle(). 


The value of the Top argument should be Topon or Topoff. If Top 
is set to TopOn, the bar will have a visible top. If Top is set to 
Topoff, the 3-D top of the bar is not plotted, making it possible to 
“stack” multiple bars on top of each other, with perhaps the 
topmost bar actually having its top displayed. 

Return Value 


Always returns CT_OK, 
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_ Bar3D 


Example 


exampte() 
begin 


WORD {, x, yz 
RECT r, SetRect(): 


SetFitlStyle( CloseDotFitl, YELLOW )s 
r @ SetRect( 30, 290, 50, 290 ); 


for ¢ {= 0; { < 12: {++ ) 
loop 


Bar30( r.LX, r.LY-(1*10), r.RX, FRY, 10, TopOn ): 
endl oop 


endfunet ion 


Textonly 


Function is ignored when in textonly mode; returns CT_OK. 


See also 


SetFillStyleQ, Bar3D0 
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Example 
example() 
begin 


WORD i, x, y3 
RECT r, SetRect(): 


SetFillStyle¢ CloseDotFill, YELLOW >: 
r = SetRect( 30, 290, 50, 290 ); 
for ( § = O¢ { < 123 {++ ) 

l 


Bar30( F.LX, r.LY-(1*10), PeRX, PRY, 10, TopOn ds 
endl oop 


endfunetion 


Textonly 


Function is ignored when in textonly mode; returns CT_OK. 


See also 


SetFillStyieQ, Bar3DQ 
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‘©-—ntax 
T Beep pitch, duration ); 


--°) WORD pitch; 
"WORD duration; 


Description 


Tells the CAP to “beep” at pitch pitch for duration milleseconds. 


Return Values . 
CT_OK Successful operation. : 
CT_BADARG Invalid value for pitch (range is 27 to 18000 Hz) 


or duration (range is 1 to 32000 milliseconds), 


/* play @ higher and higher pitches for longer and longer 
duration */ 
for( c = 0; ¢ < 20; ctt ) 
loop 
Beep( (p*c), (d*c) ); 
endl oop 


endfunct fon 


Textonty 


Sy Sends a control-G (BEL) character to the user’s terminal. 
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BitmapSend 


‘Syntax 


INT BitmapSend( rect, how, fileformat, filepath, filename ); 


RECT rect; 

WORD how; 

WORD fileformat; 

CHAR filepath{ 80 }; 

CHAR filename( maxten_xenixfilename 1; 


Description 


BitmapSend is used to send and/or display a bit-mapped graphics 
image on the CAP user’s screen. You'll need to specify the path 
and name of the file that contains the bitmap image. For this 
release of CocoTalk, only the PCX (PC Paintbrush) bitmap 
image file format is supported. 


If the filename containing the image is already available locally on 
the CAP user’s machine, the file will not be sent (unless you set 
the how argument to BM_FORCE_SEND of BM_FORCE_SEND_DISPLAY). In 
other words, in most instances, the file will not exist on the CAP 
user’s machine the first time the image is to be displayed, but 
every subsequent request for that image will be handled locally by 
the CAP and will not require a file transfer from the HOST. 


' If you get the how argument to BM_CHECK, you can use BitmapSend 
to first query the CAP to see if it: 


a) has the image file already 

b) has enough disk space to receive the file from the HOST 
if necessary, and/or 

c) has enough memory to display the image on the screen. 


If the CAP reports that it does not have the file but does have the 
storage necessary for saving the file, you can then prompt the user 
to see if they wish to receive the file. This is especially useful if 
the image file is large and transfer at 1200 or 2400 bits per second 
would cause the user to wait for more than a few seconds. 
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BitmapSend 


7hen the BitmapSend() function transfers a file to the CAP 

ser’s machine, a progress indicator appears at the bottom of the 

f-*) CAP user’s screen indicating that a graphics image is being sent. 

If the user presses ESC during the file transfer, the file transfer 

is aborted, the image is not displayed on the screen, and the 

BitmapSend(Q) function returns a value of cT_usercan (ie. user 
cancelled the operation). 


Explanation of function arguments: 

rect the area on sccaelete image should appear. 
how set to one of the following constant values: 
8M_CHECK Verify file’s existence on CAP, makes 


sure CAP has enough memory & disk © 
space. B4_CHECK does not ete OY 


the image, just checks to sco if t cam. 


©)u seo Only send the bitmap image s to 


"CAP; tell the CAP to store it but not ; 


: Splay &. 


aM Sew pis Send the bitmap image only if it doesnt 
i . “6. already. exist." oa? the CAP: 
- machine, Then display it, = 

wn_FORCE_SEWD Send the bitmap image even if it is 


already available locally on the CAP 
user's machine (ic. overwrite the 
existing file on user’s machine). Do not 
display the image. 


BM_FORCE_SENO_OISPLAY Same as 8M_FORCE_SEND but do display 
the bitmap image once it has been sent. 
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_BitmapSend — 


Siletype 


“) filepath 


filename 


Set this to BM_Pcx (no other image formats are 


available with this release of CocoTalk) 
The UNIX subdirectory wheré filename is to be 


found. Be sure to exclude trailing */* characters: - : 
ie., "/usr/fred/* is INCORRECT; the CORRECT 


path would read "/ust/fred*, .*”)- °° 


name of file (ice., iy, "computer.pex’). 
Filename is used by CAP 


Return Values 


cT_OK 
CT_HUNGUP 
“sy CT_XFERFAIL 
oe CT_NOSUCHFILE 
CT_NOTPCXFILE 
| CT_NOMEM 
CT_BADARG 
CT_NOUNIXFILE 
CT_TEXTONLY 
CT_BADDISPLAY 


CT_NOSPACE 


Successful operation 
User hung up —— 
The file transfer failed 
File doesn’t exist 

Not a .PCX image file 
CAP reports not enough RAM 

Bad value of how argument 

No such UNIX file or path 

User is not using a CAP 

User’s machine can’t display this image 
Not enough disk space on user’s machine 
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BitmapSend 


imple 


_-emple() 
begin 


*) RECT r, SetRect(); 
INT 23 


r = SetRect( 440, 90, GetMaxX-10, 160 ); 


2 = BitmapSend( r, BM_SEND_DISPLAY, BM_PCX, 
“/coconet/pexfiles", “mylogo.pcex™ ); 


/* be sure to check the value of z now, to determine 
whether or not BitmapSend() succeeded or failed...*/ 


endfunct fon 


Textonly 


Returns CT_TEXTOWLY immediately. 


») 
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Circle 


Syntax 


INT Circte( x, y, radius ) 


Description 
Tells CAP to draw a circle whose center is at x, y, and whose 
radius (measured in pixels) is radius. 

Return Value 


Always returns CT_OK. 


Example 


(7 ™\ 
: 2 exanple() 
begin 
INT ze 


Color( RED 3 
z= Circle( 320, 175, 100 ); /* draws red circle on screen */ 
endfunct fon 


Textonly 


Function is ignored in textonty mode; returns CT_oK. 


See also 


| ) Ellipse(), PieSlice() 
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CocoTalkFinish 


Syntax 
CocoTalkFinish(); 
Description 
This function must be called just before exiting an external 
program. 


It is assumed that the CocoTalkStart() function has been called 
at the beginning of the external program. These two functions 
activate and de-activate the CocoTalk library. 


Return Values 
CT_OK Successful operation 
oe CocoTalkStart() was never called 
Example 
main( argc, argv ) 
INT arge; 
CHAR *argv(]; 
hanin 
NT 23 


2 = CocoTalkStart(); 
eee do your program here if z wes CT_OK ... 


z = CocolalkFinish(): 
exit( 0 ); 


endfunct ion 


) 


~gee also 


CocoTalkStart() 
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CocoTalkStart | 


Syntax 


INT CocoTalkStart(); 


Description 


This function must be called before any other fudions in the 
external program. 


apo. 


When about to exit the external program, you must call the 
CocoTalkFinish() function. 


Return Values 


CT_OK Successful operation. : io 

CT_FAIL Function was already called. 

CT_NODIRS Could not find COCONET subdirectories 

CT_NOSCOM Could not attach/open shared memory segment. 

cT_BADTTY teed is at a tty not entered in COCONET TTY 
able. 


¢ 
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CocoTalkStart 


Example 


n¢ arge, argv ) 
ome =OFQC3 
CHAR *argvQ; 
’ begin 


INT 33 
2 = CocoTalkStart(); 
if (2 I= ok ) 
then 
/* there was a problemi */ 
end 


/*. e a ; 


eee dO program here ... 


ea e */ 
2 = CocoTatkFinish(); 
exit( 0 3 
endfunct fon 
be a ee 
ee aren e 
3-22 
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Color 


Syntax 
INT Color( ¢ ); 
WORD c; 


Description 


Tells the CAP to set the foreground color to the value of ¢ for 
subsequent CocoTalk functions involving line drawing, circles, 
rectangles, arcs, ellipses, text, etc. See the notes below for valid 
values of c. 


Notes 


The following predefined constants can and should be used to 
specify the value of the color: 


Name Equivalent value 


BLACK 0 


Cal 


BLUE 
GREEN 
CYAN 

RED 
MAGENTA 
BROW 
LIGHTGRAY 
DARKGRAY 


ee i ee 


LIGHTBLUE 
LIGHTGREEN 10 
LIGHTCYAN 11 
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Color 


LIGHTRED 12 
LIGHTMAGENTA 13 
wo) YeuLow 4 
WHITE 15 


Return Values 


CT_OK Successful operation. 


CT_BADCOLOR Invalid color value. Range: 0 to 15. 


Textonly 


Function is ignored when in textonly mode; returns CT_OK. 


~4e Also o) 


~ ColorBkgnd() 
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Syntax 
INT ColorBkgnd( c ): 


WORD c; ra 


Description 


Tells the CAP to set the background colof to the value of ¢, 


Notes 


The following predefined constants can and should be used to 
specify the value of the background color: - 


Name Equivalent value 
BLACK 


LIGHTGRAY 
DARKGRAY 
- LIGHTBLUE 
LIGHTGREEN 10 


co ea N OW Rw oe 


LIGHTCYAN 11 


LIGHTRED 12 icaoae oa vA Save 


LIGHTMAGENTA == '13 . ae pe : os ae 
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ColorBkgnd 
YELLOW 16 
WHITE 15 
: Aeturn Values 
CT_OK Successful operation. 


CT_BADCOLOR Invalid color value. Range: 0 to 15. 


Textonly 


Function is ignored when in textonty mode; returns CT_OK. 


See Also 
Color() 


bp 
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Ellipse 


Syntax 


“INT Elttpee( x, y, startangle, endangle, xradius, yradius ) 


WORD startangie; 
WORD endangles 
WORD xradius; 
WORD yradius; 


Description 
Tells the CAP to draw an ellipse centered at x, y, with a starting 
angle of startangle, an ending angle of endangle, and radii of 
xvadius (width) and yradius (height). 
Use the Color() function prior to calling Ellipse to set the color 
of the Ellipse boundary. 

Return Values 
CT_OK Operation successful. 
CT_BADANGLE Bad startangle or endangle value. Valid angle 

values. 
Textonly 


Function is ignored when in textonty mode. 


See also 


Circle) 
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Emoticon 


Svntax 


T Emoticon( x, y, number ) 


Description | 


Tells the CAP to draw one of the 28 emoticons centered at point 
x, y. Emoticons are “emotion-conveying icons", also called 
CocoFaces, that display smiles, frowns, and other facial 
expressions. These are the same 28 emoticons available in the 
Personal Mail and Discussion/Topic/Notes editors on-line. 


Return Values 

~~ CT_OK Successful operation. ~ 
’ CT_BADEMOTICON Illegal value. Valid range: 1 to 28. 
Textonly 


™-nction is ignored when in textonly mode. 
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EraseArea 


Syntax 
INT EraseArea( rect ) 
RECT rect; 


Description 


Tells the CAP to erase the area specified by rect. EraseArea() 
fills the specified rectangular area with a BLACK foreground color. 


Return Value 


Always returns CT_OK. 


Example 


example() 
begin 


RECT r, SetRect(): 
v 2 


/* first, make the full screen RED */ 

r = SetRect( 0, 0, GetMaxX, GetMaxY ); 

FilledBox( r, RED, No_Border ); 

/* now erase a large central area of the screen */ 
r = SetRect( 50, 70, GetMaxX-50, 175 ); 

z = EraseArea( r )3 


endfunct fon 


Textonly 


Function is ignored when in textonty mode. 
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EraseArea 


See also 


traseWholeScreen(), EraseBarnDoor(), EraseScreen() 
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EraseBarnDoor 


Syntax 
INT EraseBarrDoor( rect ) 
RECT rect; 


Description 


Works just like EraseArea(), but erases horizontally instead of 
vertically, creating the effect of a “barn door" closing on the area. 


Return Value 


Always returns CT_OK. 


Example 


exampte() 
begin 


RECT r, SetRect(); 
INT 2; 


/* first make entire screen BLUE */ 
z = SetRect( 0, 0, GetMaxX, GetMaxY ); 
FilledBox¢ r, BLUE, No Border ); 


/* now erase, barn-door-style, a large central area of the 
screen */ 


r = SetRect( 50, 70, GetMaxX-50, 175 ); 


2 = EraseBarrOoor( r ); 


endfunct fon 
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EraseBarnDoor 


Taxtonly 


‘unction is ignored when in textonly mode. 
, ae 


See also 


EraseWholeScreen(), EraseArea(), EraseScreen() 
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EraseScreen 


Syntax 


INT EraseScreen(); 


Description 


Tells the CAP to erase coordinates 0, 0, to GetMexX, bottony, 


which is the entire screen minus about 12 pixels (the menu bar — 


area). 


Note 
EraseScreen() is primarily used internally by the COCONET 
HOST program itself; it’s advisable to use EraseArea() or 
EraseWholeScreen() instead. ea 


Return Value 


Always returns CT_0K. 


Textonly 
Sends a Control-L (formfeed) character to the terminal, 


See also 


EraseArea(), EraseWholeScreen() 
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EraseWholeScreen 


Suntax 


T EraseWholeScreen() 


7 
Description 


Tells the CAP to erase the screen area 0, 0, to GetMaxX, GetMaxY, 
which is the entire screen. 


Return Value 


Always returns CT_OK. 


ms 


Textonly | 


Sends a Control-L (“L) character. 


A 


‘See also. 


ErascArea(), EraseScreen() 


m 
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FileReceive 


Syntax 
INT FileRecefive¢ protocol, filepath, filename ): 
WORD protocol: 


ees CHAR filepath{ 80 J; 
CHAR filenamel maxlen_xenixfitename 3; 


Description 


Tells the CAP to send the specified file to the host. The file will 
be stored as filename, in the subdirectory called filepath. 


If the filepath or filename is invalid on the HOST machine, 
FileReceive() will return ct_BaDFILE and the file transfer will not 
take place. 


Currently the only valid value for protocol is XFER_XMODEM_CRC. 
Future releases will include more protocols. 


Return values 
CT_OK Successful operation 
CT_USERCAN User cancelled operation 
CT_XFERFAIL Transmission failed | 
CT_BADFILE Invalid file name on HOST machine. 
CT_BADPROTOCOL Invalid value for protocol. 
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FileReceive 


~ «tonly 


nmediately begins an XMODEM-crRC upload file transfer. 
. FileReceive() for textonty users expects the user’s terminal to 
' immediately start sending the file. Therefore, it is up to you, the 
programmer, to prompt the user for file name, and ask the user 
to press a key to begin or cancel the transfer. It is up to you to 
determine where (i.¢., what UNIX subdirectory path) the file 
should be stored. 


See Also 


FileSend() 
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_ FileSend 


Syntax 
INT FileSend( protocol, filepath; filename >: es 
WORD protocol : 


CHAR filename[ maxlen_xenixfilename 33 
CHAR thepacnt 80 1: 


Description pg ee 


Tells the CAP to receive the specified file from the HOST, The 


CAP will display an ActionWindow on the user's screen 
prompting the user to specify the same file name as specified in 
the filename argument or a new file name for their local machine. 
The CAP then begins receiving the file from the HOST. 


If the user presses the ESC key during the transfer, the paaee 


is halted, and a signal is sent to the HOST indicating that the user . 


has cancelled the transaction. In such cases the FileSend() 
routine will return a value of cT_caNceLten; if the transfer is 
successful it will return cT_ox. 


For this release, the only valid value for the protocol argument is 
XFER_XMODEM_CRC, 

Note 
For this release of CocoTalk, the FileSend() routine uses a 
straight XMODEM-CRC for textonty mode and an enhanced 
XMODEM-CRC for CAP users. Support for YMODEM and 
ZMODEM file transfer protocols is planned for a future release 
of CocoTalk. 

Return values 


CT_OK successful operation 


CT_USERCAN user cancelled operation 
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FileSend 


T_BADFILE no such file or filepath 


.. -¥_gabprotocot Invalid protocol value. 


Textonly 


For textonly cases, as soon as FileSend() is executed, it 
immediately begins sending the file in XMODEM-CRC mode. 
This being the case, you will need to add your own prompts and 
pauses to indicate that the user should press a key to begin the 
transfer or cancel the transfer. 


O 
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FilledBox 


Syntax 
INT FilledBox( rect, insideColor, borderColor ); 


RECT rect; 
WORD insideColor: 
WORD borderColor: 


Description 
Tells the CAP to draw a box in area rect. The box is colored 
insideColor, with a border color specified by borderColor. ‘The 
border is actually a few pixels inside the edge of the box. 
If you need a special border color on the very edge of the filled 
box, set borderColor to No_8order and use a separate Rectangle() 
function with coordinates the same as the FilledBox(). 
insideColor may also be set to No_Filt, which indicates no fill 
color at all. borderColor may also be set to No_Border, which 
indicates no border. 


See the Color() reference in this manual for color values. 


Return Values 
CT_OK Successful operation. 


CT_BADCOLOR Invalid color value. 


Textonly 


Function is ignored when in textonly mode. 


See also 


Bar(), ActionWindow(), FillBox3DQ 
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FilledBox3D 


INT FilledBox30C Fr, insideCcolor, bordercolor ); 
‘ RECT Fr; 


worD insideColor; 
word borderColor; 


Description 
Same as FilledBox(, but also draws 3D-like “shadowing” around 
the edges of the box, a two-pixel wide “edge” is displayed in 
LIGHTGRAY on the top and left sides of the box, and another two- 
pixel-wide "edge" is displayed in BLACK on the bottom and right 
sides of the box. 


Because of the extra two pixel size on all four sides, the following 
restrictions apply: 


- LX must be greater than or equal to 4 
: >) LY must be greater than or equal to 4 
-“ _» RX must be less than or equal to (GetHaxx-4) 
"RY must be less than or equal to (GethaxY-4) 
arn Values 
10K Successful operation. 
CT_BADCOLOR Invalid color value. 
CT_BADARG Invalid value on one OF more of the r 
coordinates : 
Textonly 


 Bunction is ignored when in textonly mode; returns CT_OK. 


3 - 40 CocoTalk API Library 


ne 


ates 
Te ey 


Pe Te eT nee See peer re EEER NT eas Ae Ree 


FilledBox3D 


See also 


FilledBoxQ) 
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_ FloodFill 


Syntax : . os 


NT FloodFIll¢ x, y, borderCotor >; 
WORD Xx; 


WORD y; 
WORD borderColor; 


Description 


Tells the CAP to flood the area beginning at xy with the current 
fill color and pattern as previously specified by a call to 
SetFillStyicQ. borderColor is the boundary at which the filling 
does not go beyond. 


Return value 


Always returns CT_0K, 


= 
“- Textonly 


Function is ignored when in textonly mode. 
See also 


>tFillStyle() 
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ImageForget 


Syntax 
INT ImageForget( which_image ) 
WORD which_image; 


Description 
Tells the CAP to "forget" (i.e., free) the memory of the. specified 
image number, without restoring the image to the screen. Useful 
for speeding up displays if image restoration is not necessary (i.¢., 
user cancels an operation and does not proceed forward). It’s 
assumed that which_image was saved via a call to ImageSave(). 
Return Values 
CT_OK successful operation 


CT_FAIL operation failed 


Textonly 


Function is ignored when in textonty mode. 


ImageSave(), ImageRestore(), ImagePut() 
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imagePut 
ee 


ntax 


NT ImagePut( which_image, newl.X, newLY 3 


any WORD which_image; 
_ WORD newLx; ' 
WORD newLY; 


Description 


Tells the CAP to put the which_image image back on the screen 
but at a new location, the upper left coordinates of which are 
newLX and newLY, The image is then “forgotten” by the CAP 
and has to be re-saved for further manipulation. 


Return Values 
CT_OK successful operation 


- CT_FAIL operation failed 


Textonly 


Function is ignored when in textonty mode. 


~-~ also 


ImageSave(), ImageRestore(), ImageForget() 
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ImageRestore. 


Syntax 
INT ImageRestore( which_imege ) 
WORD which_image; 


Description 


Tells the CAP to put the which_image image back on the screen rar eee ee 
in the same rectangular area in which it was originally saved via. st aie ee oe to eee os 
ImageSave(). The image is then "forgotten" by the CAP and has 7. ig ge a eRe, Gare Pine BREET 
to be re-saved for further manipulation. 

Return Values 
CT_OK successful operation 


CT_FAIL operation failed 


(aN 
“ } Textonly On, SN 


Function is ignored when in textonly mode. 


ImageSave(), ImageForget(), ImagePut() 
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ImageSave 
a 


tax 
IT ImageSave( rect ); 


' J RECT rect; 


Description 


Tells the CAP to attempt to save to memory an area on the 
screen, 


Return Values 


ImageSave(), when successful, returns a value of 0 or more, 
indicating the number of the image, for future use with other 
Image functions, If unsuccessful, ImageSave() returns CT_FAIL. 


_“Textonly 
Function is ignored when in textonty mode. 
Note 
igeSave() can only save portions of the screen. The size of the 
ige in bytes must not exceed 64000 bytes. 


ImageRestore(), ImagePut(), ImageForget() 
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Line 


Syntax 
INT Linec x1, y?, x2, y2 ): 
WORD x13 
WORD yt; 


WORD x2; 
WORD y2: 


Description 


Tells the CAP to draw a single line from x1,y/ to x2,y2. 


Note 


When drawing more than a few lines, it may be wiser to use the 


Polygon() function because Polygon() is specifically designed to 
transmit the coordinates of a group of up to 254 lines. 


Return Value 


Always returns CT_OK. 


Textonly 


Function is ignored when in textonly mode. 


See Also 


PolygonQ) 
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lax 


Marker( x, y ); 


Description 
Tells the CAP to draw a small, filled, triangular marker useful for 
highlighting text, items in lists, illustrations, etc. Bear in mind 
that Marker() uses SetFillStyle() to set the fill pattern and color, 
Color() to set the line color, and Polygon() to draw the marker. 


Note 
Please note that Marker() uses the Polygon() function internally; 
i.e, it sets the PolyPoints[} array. If you call Marker() after having 
-~ set the PolyPoints{] array, you will lose your data. Use caution 
'.. When using this function if you're also planning on using the 
Polygon() function. 
Return Value 


¢ Successful operation. 
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_’ Marker 


Example 
example) ¥ 
C= begin 
8 Marker( 105, 210 ); 
Color( WHITE ); < - 


TextPlotxy( 125, 210, "This text has a marker at the left."); 
endfunct fon 


Textonly 


{ 
Function is ignored when in textonly mode. st 
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PieSlice 


Syntax 


INT PfeSlice( x, y, startangle, endangle, radius ) 


* WORD x? 
WORD y; 
WORD startangle; 


WORD endangle; 
WORD radius; 


Description 


Tells the CAP to draw a pie slice picture whose point is at xy, 
and whose radius is radius, with angles startangle and endangle. 
Valid values for startangle and endangle are 0 to 360. PieSlice 
uses current fill pattern, line thickness, and colors as specified by 
the most recent calls to SetFillStyle(), SetLineStyle(), and Color(). 


PieSlice() is typically used after a call to Circle(). The circle 
becomes the "pie" from which you draw your slice(s). When the 
= x, y, and radius arguments of PieSlice are equal to the x, y, and 
 / radius arguments of the Circle(), the slice of pie will be shown 
within the circle. If you change the values of x, y, or radius for 
the PicSlice(), the slice of pie can be displayed larger or smaller 
than the pic itself, and can appear partially or completely outside 
of the circle, : 


turn Values 
wf_OK Successful operation. 


CT_BADANGLE Bad value for startangle and/or endangle. 
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PieSlice 


Example 


example() 
begin 


Color( LIGHTBLUE ); 

Circle( 320, 175, 100 ); 

SetFillstyle( CloseDotFill, YELLOW ); 

PieSlice( 320, 175, 20, 90, 100 ); 
endfunct fon 


Textonly 


Function is ignored when in textonty mode. 


See Also 


Circle(), SetFillStyleQ 
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PixelPlot 


o---tax 
| PixelPlot( x, y, pixetcolor ); 
WORD. x} 
WORD y; 
WORD pixelcolor; 


Description 


Tells the CAP to plot a pixel at coordinates x, y. The pixel is 
displayed in the color specified by the pixelcolor argument. Sce 
the reference for Color() in this manual for color values. 


Return Values 
CT_OK Successful operation. 


_~ , CT_BADCOLOR Bad value for pixelcolor. 


) 
Example 


example() 
begin 


WORD x, y; 
iT f, 23 


k = 100; 
y = 100; 


/* draws a multicolored diagonal tine */ 
for ( § = 0; § < 100; i++ ) 
l 


oop 
2 = PixelPlot( x+i, yti, (i MOD WHITE) ); 
endl oop 


endfunct ion 
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PixelPlot 


Textonly 


Function is ignored when in textonly mode; returns CT_oK. 


C) 
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Polygon 


“Tax 


iT Polygon( mm_points ) 


e) WORD num_points; 


Description 


Sends num_points sets of xy coordinate points to the CAP which 
then draws the resulting polygon. Uses the PolyPoints array. 
You can send from 1 to 254 sets of points with one call to 


Polygon(). 


Note 


For most applications, it may be to your advantage to break up 
your drawing into several polygons, say, 10 groups of polygons 
with 24 points each rather than one huge polygon with 240 points, 
“ Large polygons make take several seconds to transfer at modem 
” sates such as 1200 or 2400 bps. In such cases, breaking up big 
polygons into smaller ones allows the user to see the image being 
created, which often is more preferable than having the user’s 
display freeze for several seconds while a huge polygon is sent. 


urn Values 
CT_OK Successful operation. 
CT_BADPOINTS Invalid number of array elements. 
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Example 
example() 
begin 


INT 2; 


PolyPotnts (0) .X = 10; 
PolyPoints(1}.X = 10; 
PolyPoints [2] .X # 300; 
PolyPoints (3} .X = 300; 


PolyPoints(0) .¥ = 100; 
PolyPoints[1]} .¥ = 200; 
PolyPoints(2}.Y¥ = 200; 
PolyPoints[3) .Y = 100; 


Polygon 


z 2 Polygon( 4); /* draws a right triangle on screen */ 


endfunct ion 


Textonly 


Function ignored when in textonly mode; returns ct_ox by default. 


See also 


Marker(Q), PolygonFill9 
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PolygonFill 


“~ntax 
NT PolygonFill( num_points ) Bete 
. ; WORD num_points; 


Description 


Same as Polygon(), but the inside area is filled using the current 
fill pattern and color as specified in the most recent call to 
SetFillStyle(), and the current line style and thickness as specified 
in the most recent call to SetLineStyle(). Assumes the PolyPoints 
array has already been initialized. The num_points argument tells 
the function how many elements of the PolyPoints array to send 
to the CAP. Legal values of num_points are 1 to 254. For larger 
polygons, split them into smaller ones. 


Note 


-. - For most applications, it may be to your advantage to break up 
your drawing into several polygons, say, 10 groups of polygons 
with 24 points each rather than one huge polygon with 240 points. 


T arge polygons make take several seconds to transfer at modem 
es such as 1200 or 2400 bps. In such cases, breaking up big 
ygons into smaller ones allows the user to sec the image being 

created, which often is more preferable than having the user’s 

display freeze for several seconds while a huge polygon is sent. 
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 PolygonFill. 


Return Values 
CT_OK Successful operation. 


: a } CT_BADPOINTS Invalid number of array elements. 


Example 


exemple() 
begin 


ae ae ee da 


rege eae i 
4 


INT 23 


z = SetFillStyle( CloseDotFIll, RED );. 
PolyPoints{0).x = 10; PolyPointetol. Ys “400; /* first sale . 


PolyPoints(i}.X = 10; sisbeincatt: Y # 2003- /* second 
fr * 
PolyPoints(2].X = 300; PolyPoints(2}.¥ = 200; /* third petr 
*/ 


PolyPoints (3) .X = 300: PolyPoints(3}.¥ = 100: Pi fourth 
pair */ aE as 


we ) 2 = PolygonFILl( & ); /* draws right triangle filled w/red 
: dots */ ica aes 


endfunct fon 


Textonly 
This function is ignored in textonly mode; returns ct_ox by 
default. 

See also 


Marker(), Polygon() 
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PopUpltemAccess 


ntax 


iNT PopUpI temAccess( item_number ); 
- } WORD ftem_number; ‘ 


Description 


The PopUpltemAccess function first checks to see if there is an 
access list for this popup menu item. 


If yes, it checks to sce if this user has an entry in the list. If not, 
it checks to sec if there’s an entry for all users in the user’s access 
group. If negative, it checks to see if there is a default access 
value (“(all)" users in “(all)* groups). The found access value is 
returned by the function. If no access list is found, it returns 
CT_FAIL. 


~ Return Values 
:* PopUpltemAccess() returns a number greater than 99: the "access 


‘, Yalue” for this user, If there was a problem, ct_Fait is returned, 
usually signifying that no access list was found. 
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PopUplitemChoose 


Syntax 
INT PopUp! temchoose( ) 
Description 
Tells the CAP to begin accepting keypresses from user. Used in 
conjunction with the other PopUp functions. 
Note 
This function is assumed to be called immediately after the call to 
PopUpltemChoose(). A call to PopUpResponse() is assumed to 
take place immediately after the call to PopUpItemChoose(). 
Return Value 


Always returns CT_oK. 


Example 


See example for PopUpMenuDisplay(). 


See also 


PopUpMenuDisplay(), PopUpltemAccess(), PopUpResponse() 


* CocoTalk API Library 3-59 


PopUpitemSet 


tax 


oe INT PopUpitemSet( itemnumber, itemtext ); 


‘ yoro i temnumber; 
CHAR itemtext[{ maxlen_popup_item_name ] ); 


Description 


PopUpltemSet() can be used to initialize a particular popup menu 
item’s name to a specified string. PopUpltemSet() is equivalent 
to the following sprintf() function call: 


sprintf( temp_popup.item{ 0 ].name, “This is the first item" 


e 
/* this is equivalent to the following lines */ 
PopUpItemSet( 0, “This is the first item" ); 


“~- 


e Yeturn Values 


ct_ox Successful operation. 


Also 


UpMenuSet(Q, PopUpMenuDisplay0, PopUpResponse() 


Syntax 5 
INT PopUpMenwWisplay( rect ) 
RECT rect; 


Description 
Tells the CAP to display the current popup ment within the 
screen area as specified in rect 

Return Value 


Always returns CT_OK. 


Example 
exampte() 
begin 


~ RECT bs 
INT 13 


/* this example displays e four-item ag Seo : 
on the. screen... Note the the - 
PopUplteaSet funct fon below to © inte! tial itd the 
neme field of the temp_popup.{itemin} erray 
structure. You'll need to use Poplip! temset() 
to initialize your ride 4 {tem names. Note 

that {tem(2), actually the third item in the 
menu, since the item array begine with the 
Oth element, is set to a predefined constant 
called POPUP_BLANK_ITEM. Use th!é conetent 
when you want to add a "blank Line” {tem to: 
seperate other {tem names in the menu. Users 
cannot select items set to POPUP_BLANK_ITEM, 
and PopUpResponse() should never return @ 
value indicating that the user selected « 
blank ftea. */ 
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PopUpMenuDisplay 


PopUpitemSet( 0, “First Item"); 
PopUpitemSet( 1, "Second Item" ); 
PopUp! temSet( 2, POPUP_BLANK_ITEM ); 
Poppi temSet( 3, "Cancel... ESC"); 


my baSetRect( 10, 10, 300, 100 ); 


PopUpMenuSet( 12019, 4, 0 ); 
PopUipdenuOisplay( b ); 
Popup! temChoose( ); 


{ = PoppResponse(); 


if ¢ ¢ # == CT_USERCAN ) OR 
( {1 == CT_ESCPRESSED ) ) TextPlotXxY( 30, 200, 
“Cancel led!"); 
else {f ( { == 0 ) TextPlotxy( 30, 200, "Chose first item"); 
else if ( § == 1) TextPlotxy( 30, 200, “Chose 2nd item"); 
else if ( 1 >= 3 ) TextPlotxy( 30, 200, “User cancelled.”); 


endfunct fon 


See Also 


poe PopUpltemChoose(), PopUpResponse(), PopUpMenuSet(), 
ey PopUpltemSet() 
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PopUpMenuForget 


Syntax 


INT PopUpMenuForget( IDcode ); 


WORD IDcode; 


Description 


This function tells the CAP to “forget” (i.c., free from memory) 
the information concerning a particular popup menu previously 
used. The particular popup menu is identified with the IDcode 
argument. 

The CAP keeps as many popup menus as possible in memory. 
When it runs out of memory for a new popup menu, the oldest 
one gets erased to make room for the new menu. Popup menus 
are identified by their ID codes. 


If the CAP finds a matching ID code in its in-memory list of 
popup menus, it removes that entry from the list. 


This function is useful when you want to change the text of a 
particular menu item or change the number of items in a menu. 
Normally, changes would not be noticed because the CAP first 
searches its memory to see if you have already displayed a popup 
menu with an ID code of [Dcode. The only way to update a 
popup menu that is already in the CAP’s memory is to call this 
function and then re-initialize and re-display the menu by calling 
PopUpltemSet(), PopUpMenuSet(), PopUpMenuDisplay(), 
PopUpltemChoose(), and PopUpResponse() again. 
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PopUpMenuForget 


Roatiupn Value 
ways returns CT_OK. a 
- ) 


Textonly 


This function does not apply when textonly is set to TRUE; it 
immediately returns a value of CT_oK. 


See also 


PopUpltemSetQ, PopUpMenuSet() 
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PopUpMenuSet 


Syntax 
INT PopUpMenuSet( IDcode, items, flags ): 


“y WORD IDcode; 
a, WORD items; 
WORD flags; 


Description 


Initializes the temp_popup data structure; assigns tesp_popup.code 
(the popup menu’s ID code) to be IDcode; sets texp_popup. items 
to be the number of items in this menu; and sets temp_popup. flags 
to be set to flags. 


goths. 


Borys rd 


Note 


The flags argument should always be set to 0. Puture ks et will au 
offer meaningful values for flags; for now, use 0. ° 7s 


—! 
d ieee mere ue eis 


the popup menu item names. See the example below for proper 
use of this function. 


Return Values 
CT_OK Successful operation 
CT_BADPOPID Illegal value for popup menu’s ID code. 
Legal values range from 10000 to 64000. 
Values less than 10000 are reserved by the 
system and should not be used. 


CT_BADNUMPOPS Invalid number of pop up items 
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PopUpMenuSet 


Fyample 


ixample() 
regin 


Sdefine PUC_TEST 15001 /* Pop Up menu Code constant */ 


PopUpl temSet( 0, “This is the first item" ); 
PopUp! temSet ( 1, "The second“ 1 
Popupl temSet( 2, “And the third 3 


/* indicate that this menu's id code is PUC_TEST, and 
that i¢ has 3 {tems, and set the flags to zero */ 
z = PopUpMenuSet( PUC_TEST, 3, 0 ); 


{* at this point, continue with calls to 
' PopUpMenwOisplay(), 
PopUp] temChoose(), and 
PopUpResponse()... */ 


endfunct fon 


See Also ' 
aan 
/ panic tewe cura: Eco UeMoxsDisplar(); 
2 ene PopUpResponse() 


ue wy, 


ae 
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PopUpResponse 


Syntax 


INT PopUpResponse(); 


Description 


When a user is presented with a popup menu, he or she select an 
item from the menu by using the UpArrow or DownArrow keys 
followed by a RETURN keypress. 


Alternatively, the user can press ESC or SHIFT-ESC. This 
function tells the CAP to send back the result code after the user 
has selected his or her choice. 

The function returns the value of the choice made. 


Return Values 


0 to temp_popup.num_{tems The value of the popup menu 
on item that the user selected. 
NY 
CT_USERCAN User cancelled the operation; 
generally this can be treated as if 
the user pressed ESC, ° 


CT_SHIFTESCPRESSED User pressed SHIFT-ESC. You 
should immediately finish up, call 
CocoTalkFinish(), and exit the 
external program. The’ user has 
indicated he or she wants to 
return to the main menubar of 
the COCONET HOST. 


CT_ESCPRESSED User pressed ESC. 
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PopUpResponse 


Textonly 


Vhen in textonly mode, PopUpResponse waits for the user to 
"5 either press ESC or type a number followed by RETURN. 
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Syntax 
INT Prompt( x, y, flags, inputtype, maxcharé $3 

t WORD x: 
| WORD y; 

WORD flags: 


WORD Inputtype: 
WORD maxchars; \ 


Description = 


Tells CAP to display a prompt on the screen, at point xy. For 
this release of the CocoTalk API Library the flags argument 
should be set to 0. The maxchars argument is thé maximum 
number of characters permitted as input. The inputtypé argument 
must be one of the following values: Bere gee 


mrstiDe Sea: yeah Sint gen 
it_text regular text input is expected;&:< 

: : Maske © alate Carey re ee : a5 
it_word a number between 0 and 64000 be expected 


it_longint a number between 0 and 2440000000 is 
it_textlines a multiple-line text prompt is expected (see 
PromptinitTat) 2°53! 


any Sear 
wt AMON 


Note y S 


will set the prompt.tnbuf string to be the actual iiser input. In 

other words, if you specified it_word for the inputtype, and the 

user typed in 12345 and pressed the RETURN key, the 

Gos prompt. {nbuf.string would be set to "12345". It’s up to you to 

ey, evaluate the prompt. inbuf string and set other variables of your 
own. The inputttype argument is used only to tell the CAP what 
kind of input to expect. aa 


No matter what value of inputtype you use, a successful Prompt() 
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Prompt 


Return Values 


TOK Heh Successful operation: user’s input 
4 available in prompt.inbuf. 


CT_USERCAN User cancelled prompt, pressed ESC 


_CT_SHIFTESCPRESSED User pressed SHIFT-ESC: end program 
so HOST can return to main menu. 


Example 
example) 
begin 
INT zy 
CHAR ss[21]; 
TextPtotxy¢ 10, 90, “Type your name below:"): 
Promptinitinbuf(); 
) 2 = Prompt¢( 10, 110, 0, ft_text, 20 ); 
. If 6 8.48 CTLOK ) 
then’ 
TextPlotxy( 10, 130, “You cancelled."); 
else 
begin 
sprintf( 88, "You typed: Xs", prompt. inbuf ); 
ON eel idald 10, 130, ss ); 


idfunct fon 


Textonly 


User can type in text and press RETURN, or simply press ESC. 


Py, ‘ 
PromptRedo(), PromptInitTxt(), PromptFreeTxt() 
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PromptFreeTxt 


Syntax 


INT PromptFreeTxt¢): 


Description 
Used to free the prompt_txt_ptr pointer (the function calls the 
caltoc() C function). This function should be called when you are 
finished using a multi-line prompt. 

Return Value 


Always returns CT_oK. 


Example 


example() 
begin 


INT 23 

z = Promptinittxt¢ 5, 2 ); 

2 = Prompt( 10, 20, 0, it_textlines, 15 ): 

/* . « « your commands to evaluate {input go here. . . */ 
z'= PromptFreeTxt(); /* free up the memory now */ 


endfunct fon 


See also 


Prompt(), PromptinitTxtQ 
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Promptlinitinbuf 


Syntax 


Prompt InitInbuf(); 


. 1 


: Description 


Used to initialize the string prompt. inbuf, which is what gets set 
when a user inputs data at a prompt. If you do not call this 
function before calling Prompt(), the system will send the contents 
of prompt. inbuf to the CAP and the user will see it as editable text 
in the prompt. 


Return Value 


Always returns CT_oK. 


Example 
“example() 
begin 
INT 23 
z = Promptinitinbuf(); /* initialize it to start with */ 


Color( WHITE ); 
TextPlotxy( 10, 0, “Type this: ‘exact input'"); 


Z = Prompt( 10, 20, 0, it_text, 15 ); 
if ( stremp( prompt. inbuf, “exact input" ) I= 0 ) 
then 


Color( RED ); 
TextPlotxy( 10, 50, “Nope. Try again."); 
goto RETRY; 

Color( GREEN ); 


TextPlotxy( 10, 90, “Good!"); 
endfunct ion 


wee Also 


Prompt(), PromptRedo() 
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PromptinitTxt 


Syntax 
INT PromptinitTxt( totalLines, visibleLines )3 


WORD totalLines; 
WORD visibleLines; 


Description 


You must call this function before using & sn ia ere prompt. 
This function allocates enough memory for your multi-line text 
buffer. When you are finished with your protipt, you must call 
PromptFreeTxt(). 


gf hd € t 
Return Values 
CT_OK Successful operation 
CT_BADARG Bad value for totalLines (valid range: 2 to 254) 


or for visibleLines (valid range: 1 to 24) 


Example 


See the example in PromptFreeTxt(). 


See also 


PromptQ), PromptFreeTxtQ) 
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PromptRedo 


mtax 
NT PromptRedo(); 
——. 
i 
Description 


Tells the CAP to re-display the prompt as currently specified. 
The current values of the prompt structure are used. Use this 
function when you are repeating the same prompt (for example, 
because the user typed in incorrect data). This function can only 
be called after a call to Prompt(). 

Return Value 


CT_OK Successful operation: user’s input 
available in prompt. inbuf. 


~ CTUSERCAN User cancelled prompt, pressed ESC 
CT_SHIFTESCPRESSED User pressed SHIFT-ESC: end program 
so HOST can return to main menu. . 


omptQ) 
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Rectangle 


Syntax 
INT Rectangle( rect ); 
RECT rect; 


Description 
Tells the CAP to draw a rectangle at points specified by rect. 


Return Value 

Always returns CT_ox. qt Se . 7 
Textonly 

This function is ignored (immediately returns CT_OK) when in 


textonly mode, 


See Also 


FilledBox(), RoundedRect(), SetRect( 
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RoundedRect 
a a Sh 


Syntax 


I RoundedRect( rect, borderColor, fillcolor 3 
" RECT rect; 
WORD borderColor; 
WORD fillColor; 
Description 


Tells the CAP to draw a rectangle with rounded corners. The 
border color is set to borderColor and the area inside the borders 
is colored fillColor. 


Return Value 


Always returns CT_ox. 


extonly 


This function is ignored (immediately returns ct_ox) when in 
textonly mode, 


©-- also 


indedRectMessage() 
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RoundedRectMessage 


Syntax 
INT RoundedRectMessage( rect, borderColor, filiColor; message ); 


RECT rect; 

WORD borderColor: 
WORD fillColors 
CHAR message [80); 


Description 
Same as RoundedRect but also tells the CAP to display a text 
string inside. ; 

Textonly 
Sends the text message followed by a ‘\n’. 


See Also 


RoundedRectQ) 
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NT Sector( x, y, startang, endang, xrad, yrad ); , lan i 
ae 


7 WORD x; 
WORD y; 


t 
WORD startang; 
WORD endang; : 
WORD xrad; 
WORD yrad; 

{ 

| 

i 


Description 


Tells the CAP to draw and fill an elliptical sector. 


Return Value 


CT_OK Successful operation. 


©) Stpaoawctg Invalid value for startang or endang (valid angle 
te . values are 0 through 359). 


. Textonly: ; 
"—ored; returns CT_OK immediately. 


See Also 


Ellipse() 
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SetDefaultFont 


Syntax 


INT SetDefaul tFont(); 


Description 


Equivalent to calling settextstyle( Defaultfont, HorizDir, 1 ). 


Return Value 


Always returns CT_oK. 


Textonly 


Ignored in textonly mode. 


See Also 


SetSmallFont(), SetTextStyleQ 
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SetFillStyle 


Cuntay 


T SetFillstyle( fillpattern, filltcolor ); 


WORD fillpattern; 
WORD fillcolor; 


Description 


Tells the CAP to change the fill pattern and fill color for 
subsequent calls to Bar(), Bar3D(Q, PieSlice(), FloodFill(Q), and 
PolygonFillQ. 


Legal values for fillpattern: 


EmptyFill 
SolidFill 
LineFIUt 
LtSlashFitl 
SlashFitl 
BkSlashFitl 
LtBkSlashFilt 
HatchFilt 
XHatchFitt 
InterleaveFilt 
WideDotFilt 
CloseDotFilt 


Legal values for fillcolor: 


Any color from 0 to 15 (BLACK to WHITE). 
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a ast 


Return Value 
(- na CT_OK 
CT_BADPATTERN 


CT_BADCOLOR 


Textonly 


SetFillStyle 


Successful operation. ... | +; - 
Illegal value for fillpattern. 
Illegal value for fillcolor. 


Ignored; returns ct_ox immediately. 


See Also 


FloodFI(, PolygonFill(), PieSlice(), Bar(), Bar3D0 
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SetLineStyle 


~ tax 
T SetLineStyle( Linestyle, linepattern, linewidth ); 


“- yorD Unestyle; 


“WORD Linepattern; 
WORD linewidth; 


Description 
Tells the CAP to initialize the line drawing settings to new values. 


Legal values of tinestyle: 


Sol {din 
Dottedin 
CenterLn © 
Dashedin 


Legal yalues of rwpatzare 

“Set to 0 for this release. 

j ” Legal values of tinewidth: 

Norm idth 
_ Thfekwideh 
> Return Values 
CT_OK Operation successful. 
_ CT_BADLIWESTYLE Invalid value for linestyle. 


CT_BADLINEWIDTH Invalid value for linewidth. 
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SetLineStyle 


Example 


example() 
begin 


> ” INT 2; 
/* draws a thick dotted line fro (40,120) to (460,390). */ 
z = SetLineStyle( Dottedin, 0, ThickWidth ); 
z= Line 40, 120, 460, 390 ); 
/* remember to reset to normat when done! */ 


z = SetLineStyle( Solidin, 0, Normlidth ): 


endfunct fon 


Textonly 


Ignored; returns Ct_oK immediately. 
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SetPalette 


Svntax 
SetPalette( fromcolor, tocolor ); 


: 7 WORD fromcolor; 
“ WORD tocolor; 


Description 


Changes the palette color value of fromcolor to the new value of 
tocolor, 


Return Value 


Always returns CT_oK. 


Textonly 


=~ 
Ignored in textonty mode. 
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SetRect 


Syntax 
RECT SetRect( Ix, ly, rx, ry ); 
WORD Ix; 
WORD ly; 


WORD rx; 
WORD ry; 


Description | % : : 


SetRect() is used to set the coordinates of & abcr structure, 
Unlike other CocoTalk functions, SetRect() teturns . a RECT 
value, not an INT value. See the Note below." t#* !** 


anette 


Note 
To use SetRect within one of your ees you'll nied * . 
declare that SetRect is of type RECT. Sea the thimple below. 

Return Value 


Returns a RECT value with the. rect’s coordinates set to the 
values by, ly, 1%, ry. 
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SetRect 


Example 


tample() 
j agin 


RECT r, SetRect(); /* note SetRect is declared to be of type 
RECT */ 


r = SetRect( 0, 0, GetHaxX, GetMaxY ); 


/* the SetRect above is equivalent to doing the following: 
r.LX = 0; 
roLY = 0; 
r.RX = GetNaxX; 


reRY = GetMaxy; 
® 


Actionlindow( r, DARKGRAY, BLACK, BLUE, * Hello, world! *); 
endfunct fon ; 
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SetSmallFont 


_ Syntax 


INT SetSmallFont(): 


Description 


Equivalent to calling setTextStyte( Smatifont, HorizDir, 4 ). 


Return Value 


Always returns CT_oK, 


Textonly 


Ignored in textonty mode. 


See Also 


SetTextStyle(), SetDefaultFont() 
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SetTextStyle 


@--atax 


IT SetTextStyle( fontnum, fontdir, fontsiz ); 


“") WORD fontnum: 
WORD fontdir; 
WORD fontsiz; 


Description 


Tells the CAP to change its font style to the new settings. 
Subsequent calls to TextPlotXY and other functions which display 
text will inherit these settings until new settings are sent. 


Valid values for fontnum: DetaultFont, smaltFont, GothicFont, 
Eurofont, TriplexFont, SansSeriffont, ScriptFont, Simplexfont, 
LcomFont. 


The fontdir argument should be set to HorizDir or Vertdir. 


: ” Valid values of fontsiz are 1-10 or UsercherSize. — 
Return Values 
CT_OK Successful operation 
BADFONTNUM Invalid font number. 
CT_BADFONTDIR Invalid font direction. 
CT_BADFONTSIZE Invalid font size. 
Textonly 


Ignored when in textonly mode. 
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SetUserCharSize 


Syntax 
INT SetUserCharSize( MultX, MultY, DivX, DivY )¢ 
WORD Mul tX: 
WORD MultYs 


WORD Divx; 
WORD DivY; oe af 


Description 
Sets the custom sizing of the text fonts. Use this function to 


shrink, stretch, and squish the "stroked" text fonts (all fonts'other 
than Defeul tFont). ; ; 


Return Values 


CT_OK Successful operation 
CT_BADARG Invalid argument(s) 
Textonly 
Ignored; returns CT_oK. 
See Also 


SctTextStyle(), SetDefaultFont(), SetSmallFont() 
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StringSend | 


Cyntax 


INT StringSend( ss ); 
“) CHAR ssf 256 }; 


Description 


Use StringSend to send text strings to textonty user displays. 


“Return Value. 


CT_OK Successful operation. 


Example | 
exanple() 


A ‘ _rexsonly = TRUE ] 


Str ingsend “Hello, worldi\n\nType your name > "): 
end 
else 


n 
TextPlotxy( 10, 100, “Hello, worldi"); 
gee SHEER 10, 120, “Type your name:"): 


endfunct ion 


Textonly 


Only use this function if textonty is set to TRUE. 
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TextFileBrowser 


Syntax 


INT TextFileBrowser( fitepath, filename, headertxt ); 


CHAR filepeth({ 80 ); 
CHAR filename 14 1; 
CHAR headertxt{ 50 Jj; 


Description 


Presents the file called filename located in path filepath to the 
user. The user can read the text file as long as he or she wishes. 
To exit the browser, the user must press the ESC key. 


The headertt argument is a string which will be displayed at the 
top of each "page" of text. 


The TextFileBrowser automatically calculates the number of 
“pages” by calculating the number of lines in the file. A “line” is 
’ a string of characters ending with a linefeed character. The 
oy number of lines per page is determined by evaluating the user’s 
"ae display capabilities. For example, EGA users see 25 lines of text 
per page, so a 250 line file would be 10 pages long. The same 
250-line file viewed in VGAHi mode would be 35 lines per page, 
or 8 pages. Textonly users can use the Personal Preferences menu 
(from the main menubar) to specify how many lines per page are 

desired (default is 20). 


You can display ASCII text files up to 999 lines long, with each 


line not to exceed 80 characters. Longer files should be broken 
up into several smaller files. 


Return Values 


CT_OK Successful operation. User exited 
the browser normally, 
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TextFileBrowser 


ST_NOSUCHFILE The specified file was not found on 
the specified path. Check the values 
of filepath and filename to make sure 

a you have the correct path and name 
a eet of the file. Remember that filepath 
should not end in ’/’; this character 
is automatically added to the string. 


CT_TFBEXITTOMAIN User pressed SHIFT-ESC from the 
browser, indicating that he or she 
wishes to immediately return to the 
main menu. You should 
immediately close any open files and 
exit the external program. 


Textonly 


Works very similarly to the CAP version. Textonty users can also 
oN view a text file using the browser. 
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7 TextPlot 


Syntax 
INT TextPlot( txt ); 
CHAR txt [(80}; 


Description 
Tells the CAP to display the text string contained i in ot at the 


current x,y coordinates. 3 


Return Value 


Always returns CT_OK. 


Textonly 
Sends the string followed by a ’\n’. 
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TextPlotXY 


Syntax 
T TextPlotxy( x, y, txt ); 
: _ 3} WORD x; 
“ WORD y; 
CHAR txt[100]; 
Description 
Tells the CAP to display the text string contained in p¢ at point 
xy. 
Return Value 


Always returns CT_oK, 


— Testonly 


Sends the string followed by a ’\n’. 
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TextPlotXY2C 
a : 
Syntax 
INT TextPlotXxy2C¢ x, y, txt, cl, ¢2 )3 
- ) WORD x; 
WORD y; 
CHAR txt {200}; 


WORD cls 
WORD c2: 


Description 


Tells the CAP to display the text string twice, once in color c2, 
then again in color cJ. Calling TextPlotXY2CQ) is the exact 
equivalent using the following four lines of code: 

Color( c2 va 

TextPlotxy( x#1, y+1, txt ); 

Color( cl ds 

, i“ TextPlotxY( x, y, txt ); 

This function is useful when plotting brightly colored text on a 
bright background. A common usage is when the background is 


GRAY OF DARKGRAY, and c2 is set to BLACK and c/ to WHITE to add a °3- 
D* feel to the text. 


Return Values 
CT_OK Successful operation. 


CT_BADCOLOR Invalid color value for cl or c2. 
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=~ample 


‘ample ) a 
. begin 

RECT r, SetRect(); 

INT 2; 


fF = SetRect( 100, 80, GetMaxX-100, 100 ); 
z= FilledBox( r, DARKGRAY, No_Border ); 
Z = TextPlotxy2c( r.Lx+10, r.LY+8, 
“This text stands out!", WHITE, BLACK ); 


endfunct fon 


Textonly 


Not designed to be used in textonty mode; sends the string twice, 
each time followed by ’\n’. 


See Also a 


TextPlotX¥() 
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WaitForESC 
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Syntax 


INT WaftForESc(): 


Description 


Tells the CAP to wait for the user to press the ESC key. 


Return Value 


cr_oK § Successful operation. 


Note 


This routine initializes a simple keyset and calls WaitForKeyset() 
internally. aa 


Textonly 


Waits for user to press ESC. 


See also 


WaitForKeyset() 
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WaitForKeyset 
a ee 


Syntax 
INT WaltForKeyset( idcode, numkeysets, flags, waitsecs 3 


WORD idcode; 
WORD numkeysets; 
WORD flags; 
WORD waitsecs; 


Description 


Tells the CAP to wait for user input. If the user’s input matches 
one of the keyset pairs, the pair number is returned in variable 
keyset.retcode. For this release, the flags and waitsecs arguments 
must cach be set to 0. Valid values for idcode are 10000 to 64000. 


Return Values 
_ CT OK Success; check value of Keyset.retcode to 
: find out which keyset was pressed 
CT_WUNGUP | "User's line hung up 
: CT_BADMUMKEYS | Bad value for numkeysets (max. is 16) 
8 


inis function is designed for use with CAPs; it will not run in 
textonly mode. It is up to you to test the value of textonty and 
if the value is set to FALSE, program alternative code for 
textonly users. . 
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Example 


example() 
begin 


INT 23 

ae ff ( textonly == TRUE ) 

Wee «+e do some alternative like “press 1, 2, or 3.."... 
else 


begin 
TextPlotxy(0,0,"Press ESC, F1, or F2 now.")s 


keyset.key1[ 0] = ESCs /* an ESC keypress */ 
keyset.key2£ 0] = 0; /* note key2 is 0 */ 


keyset.key1[ 1] = 0; /* note key is 0 */ 
keyset.key2{ 1} = Fikey;: /* note key2 is Fikey */ 


keyset.key1[ 2] = 0; /* special key: 0 %/ 
keyset.key2{ 2] = F2key;: /* note key2 fs Fekey */ 


z= WaitForKeyset( 3, 0, 0 ); 


if ( keyset.retcode == 0 ) 
TextPlotxy( 0, 20, "You pressed ESCI" 3 
else if ( keyset.retcode == 1 ) 
TextPlotxy¢ 0, 20, "You pressed FII™)s 
ar oe else if ( keyset.retcode == 2 ) 
Moe TextPlotxy¢ 0, 20, "You pressed F2I"): 
else TextPlotxy( 0, 20, "Error encountered." 3 


endfunct fon 
Values for the keyset structures 


For the keys below, set keyset.key!f n ] to the predefined 
constant (or character in single quotes) describing the desired key 
name, and set keyset.key2[ n ] to 0. 


| ESC for the ESC key 
CR for the RETURN key 


All other type the key name surrounded by single 
quotation 

ASCII keys marks. Examples: ’a’, ’>’, °3’, ’X’, 

from 33 

to 126 


WaitForKeyset ax 
—_— i 
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or keys listed below, set keyset.keylin) to 0 and set 
yset.key2[n) to the constant describing the desired key name. 


‘. Ctrlalt F3key Shi ft_F7 ALT_K 
LeftArrow F4key Shift_F8 ALTLL 
RightArrow F5key Shift_F9 ALT_M 
UpArrow Foékey Shift_F10 ALT_W 
DownArrow F7key Shi ft_F11 ALT_O 
CtriLeftArrow F8key Shift_F12 ALT_P 
CtrlRightArrow F9key ALT_A ALT_Q 
Home Fl0key ALT_B ALT_R 
Endkey Fitkey ALT_C ALT_S 
PageUp Fizkey ALT_O ALT_T 
PageDown Shift_F1 ALT_E ALT_U 
Tabkey Shift_F2 ALT_F ALT_V 
InsKey Shift_F3 ALT_G ALT_W 
DelKey Shift_F4 ALT_H ALT_X 
Fikey Shift_F5 ALT_I ALT_Y 
F2key Shift_F6 ALT_J ALT_2 
See Also 

WaitForRETURN(O, WaitForESCQ 
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Syntax 
INT Wal tForRETURN(); 
Description 
Tells the CAP to wait for the user to press the RETURN key. 


Return Values 
CT_OK User pressed RETURN, 
CT_USERCAN CAP returned a CANCEL signal: 


CT_FAIL HOST error. 


Textonly 
Works the same for textonty mode. Waits for a ASCII 
CarriageReturn signal from the user’s terminal. 

See also 


WaitForKeyset() 
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APPENDIX A: aes 
List of CocoTalk Functions “ios 


Actiorivindo rect, windowcolor, windoborder, headercotor, headertext § 
ActiorWindoSottorMessage( rect, windowcolor, messagecolor; message } 
ActionWindaClear( rect, windowcolor, windosborder es, 
Arc( x, y, startangle, endengle, xrediud; ytedtus °° - 
Bar¢ x1, y1, x2, y2 ) ane. 
Bar30¢ x1, yl, x2, y2, Depth, Top) 
Beep( pitch, duration ) a 
BitmapSend( rect, how, {mageformat, filepath, filénaine §:.” 
Circle( x, y, radius ) as on 
CocoTalkFinish() ‘ 
CocoTalkStart() 

Color( colorvatue ) 
CotorBkgnd( cotorvalue ) 
Ellipse( x, y, startengle, endangle, xredius, yradius ) 
Emoticon( x, y, number ) 

EraseArea( rect ) 

EraseBarrDoor( rect ) 

EraseScreen() 

EraseWholeScreen() 

FileRecefve( filepath, filename ) 
FileSend( fflepeth, filename ) 

FilledBox( rect, fillcolor, bordercotor ) . 
FilledBox30( rect, fillcolor, bordercotor ) 
FloodFILL( x, y, bordercolor ) 
ImageForget( which _image ) 

ImagePut( which_fmage, newx, newy ): 
ImageRestore( which_tmege ) 

ImageSave( rect ) 

Line x1, y1, x2, y2 ) 

Marker( x, y ) 
PieSl{ice( x, y, startangle, endangle, radius ) 
PixelPlot( x, y, pixelcolor ) 

Polygon( polygon_points ) 

PolygonFill( num_points ) 

PopUpi temiccess( {item number ) 

Popup! temChoose( items ) 

PopUp! temSet( it Cr, itemtext ) 
PopUpMenwisplay( rect, popup items ) 
PopUpHenuSet( IDcode, items, flags ) 
PopUpResponse( popup_ftems ) 

Prompt( x, y, flags, inputtype, maxchars ) 
PromptFreeTxt() 

Prompt initinbuf() 

PromptinitTxt( TotalLines, VisibleLines ) 
PromptRedo() , 
Rectangle( rect ) 

RoundedRect( rect, bordercolor, fillcotor ) 


t, 


qo 


c 
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RoundedRectMessege( rect, message ) 

ceartor( x, y, startang, endang, xrad, yrad ) 
lefaultFont() 
‘{UtStyle( fillpattern, fillcolor ) 
AineStyle( tinesize, linepattern, linewidth ) 

-, setpalette( fromcolor, tocolor ) 

SetRect( ix, ly, rx, ry ) 

SetSmal lFont() 

SetTextStyle( fontrum, fontdir, fontsiz ) 

SetUserCharSize( MultX, MultY, DivX, DivY ) 

StringSend( txt ) 

TextFileBrowser( filepath, filename, headertxt ) 

TextPlot( txt ) 

TextPlotxy( x, y, txt ) 

TextPlotxY2c( x, y, txt, frontcolor, backcolor ) 

WaitForESC() 

WaitForKeyset( makeysets ) 

Wai tForRETURN() 
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APPENDIX B: CocoTalk Reserved Words 


A C preprocessor substitute for the "e&" characters (boolean 
and). 


begin 
C preprocessor symbol that you can use as a substitute for the 


open brace "¢" character. 


bottomY 
The equivalent of cetMaxy minus ten to twelve pixels (which are 


reserved for the menubar area). 


BUT 
Equivalent to Ano. 


cap_info 
A structure defining the capabilities of the personal computer a 


CAP user is using at the moment. Sce Appendix C for more 
info. 

DIVIDE 
A C preprocessor substitute for the "/" character (divide 
operation). 

end 
Like begin, a C preprocessor symbol that you can use as a 
substitute for the close brace ">" character. 


endfunct {ion 
Same as end. 


endloop 
Same as end. 


endswitch 
Same as end. 


FALSE 
A constant set to the value of 0. 
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ParMaxt 
A C preprocessor symbol equivalent to cap_info.x_resolution. 


_ GetMaxY 


«1 AC preprocessor symbol equivalent to 


cap_info.y_resolution.GraphDriver 
A C preprocessor substitute for cap_info.graphdriver. 


GraphMode 
A C preprocessor substitute for cap_info.graphmode. 


loop 
Same as begin. 

MOD 
A C preprocessor substitute for the *x" character (modulo 
operation). 


Wo_Border 
Specifies no border color. 
- WoLFELL 


Specifies no fill color of FilledBox() and ActionWindow(). 


oR 
A C preprocessor substitute for the "||" characters (indicating a 
oolean or). 


news 


See Appendix C for a detailed explanation. 


textonly 
A variable, set when you call the CocoTalkStart() function, that 


indicates whether the user is connected via a COCONET Access 
Program or by an ASCII text terminal. If ASCII, textonty will 
be set to 1 (ic., true); if a CAP user, textonly will be set to 0 
(i.e., FALSE). 
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then 
Same as begin. 
ee TRUE 
OES J A constant set to the value of 1. 
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APPENDIX C: Useful CocoTalk Data Structures 


1. The RECT structure 


typedef struct rect_type 
in 
WORD LX, LY, RX, RY: 
RECT; 


The RECT structure is one of the most common structures used by 
CocoTalk functions, RECT refers to "rectangle," and the RECT 
structure is simply a definition for holding the values of two sets of 
points: the upper-left-hand corner of a particular rectangular area, 
and the lower-right-hand corner of the area. 


Note that each x and y value must be a WORD value: that is, it 
must have a value between 0 and 65535. Theoretically, this 
provides for screen resolutions of up to 65,535 pixels horizontal by 
65,535 pixels vertical! Practically speaking, the values for x and y 
should not exceed Gettaxx and GetMaxy, respectively. For example, 
for EGA screens, the possible values of x would be 0 to 639, and 
for y would be 0 to 349. If you specify values greater than GetHaxx 
or GetMaxy, those values will be "clipped", or set to GetMexX or 
GetNaxY, respectively, 


The SetRectQ) function provides an easy way to set the four values 
of a RECT variable. For example: 
exanple() 
in 
RECT r, r2, SetRect(): 


r= SetRect( 10, 30, 405, 225 ); 
r2 = SetRect( 0, 0, GetMaxX, GetMaxY ): 


endfunct fon 


In the first case, the RECT variable r is set such that the upper- 
left-hand point (r.LX, r.LY) is set to (10, 30), and the 
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lower-right-hand point (r.RX, r.RY) is set to (405, 225). In the 
ond case, 12 is set to the coordinates of the entire screen: the 
er-left-hand point (r.LX, r.LY) is set to (0, 0), and the lower- 

_ it-hand point (r.RX, r.RY) is set to (Getaxx, GetMaxy). 


2. The cap_info structure 


struct cap_info_rec 


begin 
CHAR phone{ maxlen_telephone J]; /* phone number they dialed 
*/ 


direct_or_normat; /* direct or normal mode */ 
pref_textcolor; /* text color preference */ 
graphdr iver; /* the graphics driver */ 
x_resolution; /* horiz. screen resol. */ 
y_resolution; /* vert. screen resol. */ 
bot_bar; /* bottom area for menubars 


J 
max_colors; /* mamber of colors avail. 
. 


graphmode; /* graphics mode */ 
max_patette; /* size of palette */ 
major_version; /* the major version no. */ 
minor_version; /* the minor version no. */ 
model : /* the CAP model */ 
regstatus; /* CAP registratjon status 


cap_info; 


thecking the values of the cap_info fields, you can find out lots 
or information about both the user’s display as well as the user’s 
COCONET Access Program. 


You can only check the values of cap info when the textonly 
variable is set to FALSE. That is, when textonly is TRUE, it 
means the user is connected via ASCII text mode, and therefore is 
not using a CAP. So none of the fields have meaningful values. 
When textonly is set to FALSE, it means the user is connected via 


‘a COCONET Access Program. This is when the information 


stored in the cap info structure becomes useful. 
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Some of the cap info fields have been included in pre-defined 
macros for your convenience when programming. These are: 


Pre-defined macro Equivalent meaning 


GetMaxX cap_info.x_resolution 

GetMaxy cap_info.y_resolution 
GraphDriver cap_info.graphdriver 

GraphMode cap_tnfo.graphmode 

Hal f_x (WORD) (cap_info.x_resolution / 2) 


Half_Y (WORD )(cap_info.y_resolutton / 2) 


You can determine the screen resolution of a CAP user’s display by 
checking the values of Getwaxx and cetHaxy. For example, 4 
common use of GetNaxX is to use its value when apecifying the X 
coordinate of the lower-right-hand point of a rectangular area. To 
display a centered box on the screen, tegardiess of the screen 
resolution, it’s imperative to know the value of thé display’s x 
resolution. Take a look at the following example function: 


enti ng c : : 
RECT r, SetRect(); a 
Color( BLUE ); eae 
F = SetRect( 133, 150, (GetMaxx-133), 250 ); 
Rectangle( r )3 


endfunct fon 


This function displays a blue rectangle that is centered in the 
screen. The rectangle’s left side is 133 pixels in from the left. The 
rectangle’s rigtht side is 133 pixels in from the right. Thus, it 
appears centered on the screen. Granted, the rectangle will appear 
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“fattes" on Hercules displays than on EGA/VGA displays, because 
Hercules displays have a wider x resolution. To compensate for 
t, you could rewrite the example code to do the following: 


cy Bxample2gy 
7 begin © 


RECT 7, SetRect(); 
WORD delta_x, K; 


if ¢ textonly == TRUE ) goto SkipOver; 
ws GraphOrjyer == Herctono ) 
en 


Color( K ); 
ea: = seengcte (133+delta_x), 
Ro sist ci Te C(GethaxX-del ta_x)-133), 
eet: ae 
(8 Rectangles pp 
Skipovers 7 bee. 
endfunction : | 
umple2 above, the if statement checks to see if the CAP user 
ag a Hescules monochrome graphics display or not. If yes, 


delta_x is set to 39, and K is set to waite (if K were swe, it 
would be translated to stack by the CAP). 


3. The PolyPoints array 


struct point_Record 
begin 
WORD X, Y; 
ma PolyPofnts£ maxnum_polypoints J; 
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The PolyPoints array is used by the Polygon() and PolygonFillQ 
functions to plot line-drawn polygons on the screen. The polygons 
can be as simple as a triangle and as complex as a map‘of North 
America. 


In order to use the Polygon() and PolygonFill() functions you need 
to first initialize the PolyPoints array. See the examples for Polygon 
and PolygonFill() in the Reference for more information. 
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Appendix D : 
List of CocoTalk Error Values . 
CT_OK -1 Operation was successful, ~~” 
CT_XFERFAIL -5 Operation failed. SRR 
CT_BADPROTOCOL -9 Bad file transfer protocol specified. . 
CT_BADFILE -10 Bad filename and/or filepath specified. 
CT_NOTPCXFILE -11 Bitmap image was not in PCX format. 
CT_NOMEM -12 Not enough CAP memory for _ 
CT_BADARG -13 Bad argument value. * : Ore 2! a) ere 
ccguoumiiits -14 Bad filename and/or spa ince, 
CT_TEXTONLY -15 In festoaly imode; functiod ignored. * : 
CT_BADDISPLAY -16 Bad CAP display for iia aipehti, ? : 
CT_USERCAN -17 User cancelled - ewe bm the 

: operation. 2 he o ‘i : 
CT_BADCAP -18 CAP version out of date for oe function. 
CT_NOSPACE -19 Not enough disk space on CAP uber’s 

machine. 

CT_INVALIDARG -20 Invalid argument. 
CT_BADCOLOR -21 Invalid color value specified. | 
CT_BADFONTNUM -22 Invalid font number specified. 
CT_BADFONTDIR -B | Invalid font direction. a ate 
CocoTalk API Library Dit 
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UDrouTsize 

~IADENOTICON 
RED CT_BADAMGLE .... ; eas 

__ CT_TEXTTOOLONG - 

| CT_BADPOINTS > 
7 STEAL Gg get 2 


 GT_NOSCOM 


« 


"GY _BADPOPID 


GT_ALROYSTETD 


- STBADTTY 


" CTLBADPATTERN . - 


—_FIAADLINESTYLE = 


GT _SADLINEMIDTY 


~ GT_AAMENOT FOUND >. 
; ay 


eR SHAD 


45 


Invalid font size. 


Invalid emoticon (CocoFace) number. 


Bad angle value. 


. Too many characters in string. 


Invalid number of points. 


. Operation failed. 


Internal 
unavailable, 


error; shared memory 


‘Invalid value for PopUp meau ID code. 


Invalid number of PopUp menu items, 


. Bad number of keyset elements. 


User name not found. 


Not in textonly mode. 
Could not find COCONET Unix 


- CocoTalkStart() already run. 


Current TTY not in COCONET TTY 


. Table. 


Bad pattern number specified. 
Invalid line style value. 
Invalid line width value. 
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CT_IMAGESAVEFAIL -46 CAP could not save image. 


CT_HUNGUP -99 User hung up -- exit program 
immediately! 


CT_BADCOCOTALK -100 CocoTalkStart() wasn’t called 
successfully, 


CT_TFBEXIT -101 User exited TextFileBrowser() normally. 

CT_TFBEXITTOMAIN -102 User pressed SHIFT-ESC from 
TextFileBrowser -- exit program 
immediately, as user has requested to 
return to main menubar. 


CT_ESCPRESSED 256 User pressed ESC key. 


CT_SHIFTESCPRESSED 257 User pressed SHIFT-ESC key - exit 
program immediately, as user has 
requested to return to main menubar. 
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ActionWindow 3-3, 4, 37, 86 

ActionWindow3D 3-5, 6 

Action WindowBottomMessage 36,7 8 
ActionWindowClear 3-8 : ee 
Arc 3-9, 10 
Bar 3-11, 79 2 abe Rases * 
Bar3D 3-12, 13, 80 oe oe 
Beep 3-14 ates Te, 
BitmapSend 3-15, 16, 17, 18 hte eA ee 
Circle 3-10, 19, 50, 51 woe EE Br os 
CocoTalkFinish 3-20, 21, 67 ~ ee ree tay 
CocoTalkStart 3-21, 22 
Color 3-10, 19, 23, 24, 39, 1 12,7276 95 " 
ColorBkgnd 3-25, 26 Me tees TR 
CT ‘ ALRDYSTRTD 4-13 copkgey ta 
CT_BADANGLE 3-27, 50, 78; 4-13 ne a ae 
CT_BADARG 35, 14, 1, 473,85; Aid 
CT_BADCAP 4 4-12 : ee 
CT_BADCOCOTALK 4-14 

CT_BADCOLOR 3-3, 5, 6, 8, 24, 26, 39, 40, teh 8S, 418 
CT_BADDISPLAY 3-17; 4-12 

CT_BADEMOTICON 3-28; 4-13 

CT_BADFILE 3-35, 38; 4-12 

CT_BADFONTDIR 3-88; 4-12 

CT_BADFONTNUM 3-88; 4-12 

CT_BADFONTSIZE 3-88; 4-12 

CT_BADLINESTYLE 3-82; 4-13 

CT_BADLINEWIDTH 3-81; 4-13 

CT_BADNUMKEYS 3-98; 4-13 

CT_BADNUMPOPS 3-66; 4-13 

CT_BADPATTERN 3-81 4-13 

CT_BADPOINTS 3-54, 57; 4-13 

CT_BADPOPID 3-66; 4-13 

CT_BADPROTOCOL 3-35, 38; 4-12 

CT_BADTTY 3-21; 4-13 

CT_BADUNIXFILE 4-12 
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2T_ESCPRESSED 3-62, 67; 4-14 
T FAIL 3-20, 21, 43-46, 58, 101; 4-13 
>T_ HUNGUP 3-17, 98; 4-14 
©" CT_IMAGESAVEFAIL 4-13 
’ CT _INVALIDARG 4-12 
CT NAMENOTFOUND 413 
CT_NODIRS 3-21; 4-13 
CT _NOMEM 3-17; 4-12 
CT _ NOSCOM 3-21; 4-13 
CT_NOSPACE. 3-17, 4-12 
CT NOTPCXFILE 3-17; 412 
CT NOTTEXTONLY 4-13 
CT_OK 3-5, 6, 8-14, 17, 19-21, 24, 26-29, 31, 33-35, 37, 39, 40, 
42-45, 41, 48, 50, 52-55, 57, 59-61, 64, 65, 70-76, 78-79, 81-84, 
87-91, 93-95, 97-98, 101; 4-12 
CT_SHIFTESCPRESSED 3-67, 69, 73; 4-14 
CT" TEXTONLY 3-17, 18, 4-12 
no  TEXTTOOLONG 33, 5, 6; 4-13 
- CT! _TFBEXIT. 4-14 
mom. CT: TEBE MAIN 3-92; 4-14 — 
cr “USERCAN' 3-16, 35, 37, 62, 67, 70, 74, 101; 412 
35; 4-12 


ImagePut 3-44 
oc. ImageRestore 3-45 
w) ImageSave 3-43, 45, 46 

Ling 3-47, 83 
~ Markes 3-48, 49 
as) +, a h8 80 
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PixelPlot 3-52, 53 
Polygon 3-47, 48, 54-56 
PolygonFill 3-56, 57, 80 

é '  PopUpltemAccess 3-58 

aus) PopUpltemChoose 3-59, 62, 63, 66 

ve PopUpltemSet 3-60, 61, 62, 63, 66 
PopUpMenuDisplay 3-61, 62, 63, 66 
PopUpMenuForget 3-63 
PopUpMenuSet 3-62, 63, 65 
PopUpResponse 3-59, 61, 63, 66, 67 
Prompt 3-69, 70-74 
PromptFreeTxt 3-71, 73 
PromptlnitInbuf 3-70, 72 Hana, Sea ee gg, oe 
PromptinitTxt 3-69, 71, 73 oe a 
PromptRedo 3-74 * . Se oie eee 
Rectangle 3-39, 75 
RoundedRect 3-76, 77 
RoundedRectMessage 3-76 
Sector 3-78 — 

ae SetDefaultFont 3-79 

AEN SctFillStyle 3-11, 12, 13, 42, 48, 50, 51, 56, 57, 80 

mee SetLineStyle 3-50, 56, 82, 83 

SetPalette 3-84 

SetRect 5-4, 6,15, 18, 27; 38, 85, 8,96 

SetSmallFont 3-87 

SetTextStyle 3-79, 87, 88 

SetUserCharSize 3-89 

StringSend 3-90 wey ee cath” BOR et Woe dees, “Fee eee Rai 

TextFileBrowser 3-91, 92 Ce rae Bee Pe Oe ee 

TextPlotXY 3-49, 62, 70, 72, 88, 90, 94, 99 

TextPlotXY2C 3-95, 96 

WaitForESC 3-97 

WaitForKeyset 3-97, 98-100 

WaitForRETURN 3-101 
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